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