PHP Classes

Class Calendar: Generate month calendar arrays

Recommend this page to a friend!
  Info   Screenshots Screenshots   View files View files (5)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 856 All time: 4,080 This week: 131Up
Version License Categories
class_calendar 1.0.0GNU Lesser Genera...Time and Date
Description 

Author

This class can generate multi-dimensional arrays containing the days of any given month across the span of weeks that the month days occupy.

It takes a given month and year as parameters and it fills the multi-dimensional array, that represents the weeks and the week days, with the respective number of the days of the month.

The array positions that represent days before and after the current month are filled with 0.

The class can also return the month name, month length in days, tell you if a given year is a leap year or not, and the week day name of a given day of the month.

Also, worth noting, the function valid_date will make sure that any month, day, and year are within valid parameters. For example, using the date 13/32/2005 by default is invalid. If you pass this date to valid_date, it would convert that date to 2/1/2006. This is important if accepting user input from a calendar.

Picture of Ken Stanley
Name: Ken Stanley <contact>
Classes: 2 packages by
Country: United States United States
Age: 46
All time rank: 1387202 in United States United States
Week rank: 312 Up38 in United States United States Up

Details

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! NOTE TO ALL USERS: IF YOU DO NOT READ THESE INSTRUCTIONS (YES, I WILL KNOW!) THEN !! !! PLEASE DO NOT EMAIL ME FOR SUPPORT! I WILL SIMPLY RESPOND AND TELL YOU TO READ !! !! THIS FILE! YOU HAVE BEEN WARNED! I TOOK THE TIME TO WRITE THIS, YOU COULD AT !! !! LEAST TAKE THE TIME TO READ IT! !! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ======================================================================================= Contact Information: If you find a bug, by all means please send me an email and describe to me how to reproduce it. If you can include your source files, it will greatly speed up my response time to you. If you have read, and reread this document, and you still cannot get it to work, then by all means send me an email, and I will do my best to help you (as my time and workload permit). But, you MUST demonstrate to me that you have read this document. Ken Stanley <phpclasses@kennethpaul.com> ======================================================================================= Requirements: PHP 4, and Apache compatible web server This software was built using PHP 4 and Apache 1.3.33. While everything in this class should be cross-compatible, due to lack of resources and desire, I have not checked. If you are using different setups and find problems, and can fix them, please send me unified diffs (diff -u my_file your_file) and contact information you'd like me to display. This software doe not use any special PHP modules, so any installation _should_ work. Optional: SQLite 1.0.3 from PECL <http://pecl.php.net/get/SQLite-1.0.tgz> If SQLite support is not present or not enabled, then you will not have access to the SQLite features. By this, I mean that add_event, del_event, get_event and num_events will always return FALSE. The rest of the class will function as normal. ======================================================================================= TODO: Allow for the day of the week to optionally start on a Monday. Translate into other languages (I NEED HELP WITH THIS, PLEASE!) ======================================================================================= I. Introductions ==================== Congratulations on picking my calendar class! I hope you will find this as useful as I have. The benefit to this class over PHP's date() function is that you are not limited to date()'s 1901-2038 limitation from PHP. You can reasonably now take your calendars as far back as 1752 with accuracy with the English calendar (anything before that, use at your own risk). II. Usage =================== Included with this distribution you should have recieved index.php which contains example usage that you can see in action. Let's go over a few key points, just so there is little misunderstanding: Create a new instance of the class: <?php include('class_calendar.php'); $cal = new calendar(); print_r($cal->get_month(1, 2005)); // Prints out an array for January 2005 ?> Set a valid range of years: <?php include('class_calendar.php'); $cal = new calendar(); $cal->min_year = 1901; $cal->max_year = 2038; print_r($cal->get_month(0, 2039); // Prints out an array for December 1901 ?> Let's stop here for a second. Did you notice something odd about the last example? I hope so! The dates WILL roll over automatically. It does the hard work of ensuring that months are 1-12, and if you set it, the years are within min and max ranges. What's not shown here, and automatically done, is it will roll over the days too. If you use something like 0, any negative number, or a number greater than the total days of a month, it will resepctively roll everything over accordingly. The hardest part of this library is formatting your calendar into HTML. Let me give you a simple example: <?php include('class_calendar.php'); $cal = new calendar(); $cal->pad_dates = TRUE; $array = $cal->get_month(1, 2005); echo "<table border=0>\n"; echo "<tr>\n"; echo "<td colspan=7 align=center>\n"; echo $cal->day_name($cal->get_day(1, 1, 2005)) . ", " . $cal->month_name(1) . ", 2005\n"; for ($i = 0; $i < 6; $i++) { echo "<tr>\n"; for ($j = 0; $j < 7; $j++) { if ($array[$i][$j] != 0) echo "<td>" . $array[$i][$j] . "</td>\n"; else echo "<td>&nbsp;</td>\n"; } echo "</tr>\n"; } ?> This outputs a real simple calendar: Saturday, January, 2005 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 There is now the ability to define what day of the week your calendar uses. Simply set the start_monday to either 0 or 1 (0 = Sunday; 1 = Monday). Since there is now language support included with class_calendar, if you choose a supported language, it will automatically adjust for the start of the week for you! Just set the language variable to your two-letter country code (i.e. one of 'en', 'hu', 'fr', 'de', or 'it'). If you wish to add your language to the calendar, just edit class_calendar.php and add your language to the calendar() constructor or email me directly with your translation and I'll add it for you. III. SQLite Support ==================== To take full advantage of this class, you should have SQLite support included in PHP. This can be done by compiling the SQLite module located at http://pecl.php.net/get/SQLite-1.0.tgz and following these simple instructions: a. Run the following command and parameters (as root): `pear install sqlite` Or b. Install the module by hand: > wget http://pecl.php.net/get/SQLite-1.0.3.tgz > tar xzf SQLite-1.0.3.tgz > cd sqlite > export PHP_PREFIX="/usr" > $PHP_PREFIX/bin/phpize > ./configure > make > make install One of the two above steps will install sqlite.so into your default PHP extensions directory. After doing that, the only thing left to do is to create the empty database file for SQLite to use: (We'll use /opt/www/htdocs/include as the directory that class_calendar.php and class_sqlite.php are in.) > cd /opt/www/htdocs/include > mkdir db > chmod 1777 db > touch db/calendar.sdb > chmod 666 db/calendar.sdb It is very important that the webserver can not only write to the file, but also to the directory that the file is in. This has been tested and found to work just fine. For those that are unfamilar with stick-bit permissions (the 1 in 1777), this simply tells the filesystem that anybody can write to the directory, but only the owner can delete the files they have created. Simply put, it's a security measure. And thats it! The class will try to load the SQLite module, and if that is successful, it will look for the database file. If it can properly write to the file it will then, and only then, allow you to use the SQLite features of this class. IV. Prologue ==================== This class has aimed to be as simple to use as possible. While the included index.php has many lines of code in it, it is only to demonstrate every feature of this class. You could invariably write your calendar in as few as 30-40 lines of code (if not, less). While this software has been pretty well tested by me, there may be a bug or two hidden in there somewhere. If you decide to help the development of this class by submitting a bug report that you include as much information as you can on how to reproduce the bug in question; include the section of code causing the bug, if you can. I will do my very best to respond as quickly as possible. Due to time constraints (i.e. job, personal life, etc) I may not be able to respond right away. Please be patient. The quality of this work is very important to me, as are the happiness of my users. I want this to be the best damned calendar anybody has ever seen or used. V. Acknowledgements =================== I'd like to thank a couple people who have contributed with either suggestions or code: Koós Zoltán - For writing the math to start the week on Sunday or Monday and for the Hungarian translation. Chris Staniek - For suggesting that I impliment database storage in my calendar. Jeremy Speer - For inadvertantly introducing me to the idea of using SQLite. VI. Developer's API =================== Below are the class API functions you can use on your own: (Refer to index.php for live implementations) Name: calendar() [class constructor] Params: string lang, string database_filename Returns: void Description: Sets up connection to SQLite database_filename, and if necessary, it will create the database first (first run). You MUST create a subdirectory and chown it to your webserver's user:group! After doing that, you MUST make the file writeable by the webserver (e.g. chmod 666 <file>). Not doing this will generate a read/write error. Name: get_month() Params: int month, int year Returns: array() Description: Returns a multi-dimension array containing the calendar month. The first layer of the array are the weeks, and the second layer are the days: week 1: sun, mon, tue, wed, thu, fri, sat week 2: sun, mon, tue, wed, thu, fri, sat week 3: sun, mon, tue, wed, thu, fri, sat week 4: sun, mon, tue, wed, thu, fri, sat week 5: sun, mon, tue, wed, thu, fri, sat week 6: sun, mon, tue, wed, thu, fri, sat This is for easy user-formatting. See README for example code. Name: get_day() Params: int month, int day, int year Returns: int Description: Returns the day of the week for the given date as a number between 0-6: 0 = Sunday/Monday 1 = Monday/Tuesday 2 = Tuesday/Wednesday 3 = Wednesday/Thursday 4 = Thursday/Friday 5 = Friday/Saturday 6 = Saturday/Sunday Name: day_name() Params: int day, int short Returns: string Description: Converts the numerical format of month (0-6) into human-readable format. You can control the size of the name by passing either a 1 (Full), 2 (First 3 letters), or 3 (First letter only) as the second parameter. Name: month_name() Params: int month, int short Returns: string Description: Converts the numerical format of month (1-12) into human-readable format. You can control the size of the name by passing either a 1 (Full), 2 (First 3 letters), or 3 (First letter only) as the second parameter. Name: is_leap() Params: string year Returns: bool TRUE/FALSE Description: Returns either TRUE or FALSE depending on whether a year is a leap year or not. Name: month_length() Params: int month, int year Returns: int Description: Returns the length of given month for given year. Name: valid_date() Params: int month, int day, int year Returns: void Description: This function takes care to ensure the validity of the date given. E.g. -1/01/2005 would be converted to 12/01/2004, and 13/01/2005 would be converted to 01/01/2006. Name: valid_month() Params: int month, int year Returns: void Description: Used in valid_date to roll over the month so it stays within 1-12 constraints. Name: valid_day() Params: int month, int day, int year Returns: void Description: Used in valid_date to roll over the day so it stays within 1-(whatever the last day is) constraints. Name: valid_year() Params: int year Returns: void Description: Used in valid_date to roll over the year so it stays within user-specified constraints. NOTE: This function is COMPLETELY optional. To disable it's use, DO NOT SET $this->min_year or $this->max_year!!!! Name: add_event() Params: int month, int day, int year, mixed string Returns: bool TRUE/FALSE Description: Adds an event for given month/day/year to the SQLite database. Name: del_event() Params: int id Returns: bool TRUE/FALSE Description: Removes an event from the database by given id. Name: get_event() Params: int month, int day, int year Returns: mixed event Description: Retrieves an event for the given month/day/year from the database. Name: num_events() Params: int month, int day, int year Returns: int rows or bool FALSE Description: Returns the number of events for given month/day/year.

Screenshots  
  • class_calendar.png
  Files folder image Files  
File Role Description
Accessible without login Plain text file ChangeLog Doc. Notes of all changes and by when and whom they are made by.
Accessible without login Plain text file class_calendar.php Class Main Class
Accessible without login Plain text file class_sqlite.php Class Simple SQLite API
Accessible without login Plain text file index.php Example Advanced Usage Example
Accessible without login Plain text file README Doc. License, Examples, and Documentation

 Version Control Unique User Downloads Download Rankings  
 0%
Total:856
This week:0
All time:4,080
This week:131Up