Class Calendar: Generate month calendar arrays

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! 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.