Dates in qCal are represented by the qCal_Date object (naturally). qCal_Date is immutable, meaning once you instantiate it, there is no way to change the date it represents. So if you need a new date, create a new object.
new qCal_Date( [ int $year [, int $month [, int $day [, bool $rollover ]]]] )
The year can be any integer between 1902 and 2037, inclusively. This is a limitation imposed by PHP itself and unless I can find a way to represent dates without using unix timestamps, this limitation will remain. Also, this range may differ depending on your operating system. See PHP's mktime function documentation for more information.
The default value is the current year.
Month can be any value from 1 to 12.
The default value is the current month.
Day can be any value from 1 to the amount of days in the specified month (between 28 and 31).
The default value is the current day.
If set to true, the month and day parameters can be more or less than their normally allowed values, resulting in a rollover. For instance, if month is specified as 1 and day is specified as 32, the resulting qCal_Date object will represent February 1st.
The default value is false.
$date1 = new qCal_Date(2010, 1, 10); // results in January 10th, 2010 $date2 = new qCal_Date(2010, 1, 35); // invalid, and will throw a qCal_DateTime_Exception_InvalidDate exception $date3 = new qCal_Date(2010, 1, 35, true); // results in February 4th, 2010 because the rollover parameter was set to true
You can also generate a qCal_Date object from a string such as “January 1st, 2010” by using the static “factory” method. Any value that can be passed to PHP's strtotime function can be passed to the factory method (although any time portion of the string will be ignored).
qCal_Date qCal_Date::factory( string $date )
The date parameter can be either a string representing a specific date, or a unix timestamp.
$date1 = qCal_Date::factory("January 21, 2010"); $date2 = qCal_Date::factory("tomorrow"); // will result in whatever tomorrow's date is $date3 = qCal_Date::factory("now"); // will result in today's date $date4 = qCal_Date::factory(time()); // will result in today's date
qCal_Date implement's PHP's magic __toString() method, which allows you to simply print it out to get a human-readable date.
$date = new qCal_Date(2010, 1, 10); echo $date; // will output "01/10/2010"
If you need the string output in a different format, use the qCal_Date::setFormat() method. All subsequent calls to __toString() (basically any time you print out the object) will output using the format you specified. qCal_Date::setFormat() accepts the following date-related metacharacters accepted by PHP's date() function: d, D, j, l, N, S, w, z, W, F, m, M, n, t, L, o, y, Y, c, r, and U. Any other metacharacters are simply output as-is. You can escape metacharacters with a backslash. Characters not listed above do not need to be escaped.
$date = new qCal_Date(2010, 1, 10); $date->setFormat("Y"); echo $date; // outputs "2010" $date->setFormat("l, F \the jS, Y"); echo $date; // outputs "Sunday, January the 10th, 2010"
If you need to convert the date to a string, but don't need to print it out, call qCal_Date::format(). Calling this method will not change the way the object prints like qCal_Date::setFormat() does.
$date = new qCal_Date(2010, 1, 10); $string = $date->format("m/Y"); echo $date; // still outputs "01/10/2010" because we did not call setFormat() echo $string; // outputs "1/2010"
qCal_Date has several convenience methods for doing some pretty nifty things with dates. There will be more and more of these functions in future versions, so be sure to check back here often.
This method allows you to find things such as the third Sunday of the month, or the second to last Tuesday of the month.
qCal_Date getXthWeekdayOfMonth( int $xth [, mixed $weekday [, mixed $month [, int $year ]]] )
Either a positive or negative integer specifying which weekday of the month you are requesting. For instance, if you need the second Tuesday of the month, this value would be 2. If you need the second to last Tuesday of the month, this value would be -2. This is the only required parameter.
This can either be a string such as “sunday” or an integer such as 0. If you specify an integer, this method uses 0 for Sunday through 6 for Saturday. If you do not specify this parameter, whatever weekday the object currently represents will be used. So if the qCal_Date object is for January 10, 2010, Sunday will be used.
This can either be a string such as “January” or an integer such as 1. If you specify an integer, this method uses 1 for January through 12 for December. If you do not specify this parameter, whatever month the object currently represents will be used. So if the qCal_Date object is for January 10, 2010, January will be used.
This must be a valid year from 1902 to 2037 (this could vary depending on your operating system). If you do not specify this parameter, whatever year the object currently represents will be used. So if the qCal_Date object is for January 10, 2010, the year 2010 will be used.
$date = new qCal_Date(2010, 1, 10); // Sunday, January 10th, 2010 $first_sunday_in_january = $date->getXthWeekdayOfMonth(1); // will return a qCal_Date object for January 3rd, 2010 $first_tuesday_in_january = $date->getXthWeekdayOfMonth(1, "tuesday"); // will return a qCal_Date object for January 5th, 2010 $second_to_last_wednesday_in_january = $date->getXthWeekdayOfMonth(-2, "wednesday"); // will return a qCal_Date object for January 20th, 2010 $second_monday_in_february = $date->getXthWeekdayOfMonth(2, 1, 2); // will return qCal_Date object for February 8th, 2010 $second_monday_in_february = $date->getXthWeekdayOfMonth(2, "monday", "february"); // the previous example could also be done like this $last_sunday_in_august = $date->getXthWeekdayOfMonth(-1, "sunday", "august"); // will return qCal_Date object for August 29th, 2010 $last_sunday_in_december_2011 = $date->getXthWeekdayOfMonth(-1, "sunday", "december", 2011); // will return qCal_Date object for December 25th, 2011 $first_sunday_in_january_2012 = $date->getXthWeekdayOfMonth(1, 0, 1, 2012); // will return qCal_Date object for January 1st, 2012
This method allows you to find things such as the third Sunday of the year, or the second to last Tuesday of the year.
qCal_Date getXthWeekdayOfYear( int $xth [, mixed $weekday [, int $year ]] )
Either a positive or negative integer specifying which weekday of the year you are requesting. For instance, if you need the second Tuesday of the year, this value would be 2. If you need the second to last Tuesday of the year, this value would be -2. This is the only required parameter.
This can either be a string such as “sunday” or an integer such as 0. If you specify an integer, this method uses 0 for Sunday through 6 for Saturday. If you do not specify this parameter, whatever weekday the object currently represents will be used. So if the qCal_Date object is for January 10, 2010, Sunday will be used.
This must be a valid year from 1902 to 2037 (this could vary depending on your operating system). If you do not specify this parameter, whatever year the object currently represents will be used. So if the qCal_Date object is for January 10, 2010, the year 2010 will be used.
$date = new qCal_Date(2010, 1, 10); // Sunday, January 10th, 2010 $first_sunday_of_year = $date->getXthWeekdayOfYear(1); // will return a qCal_Date object for January 3rd, 2010 $first_monday_of_the_year = $date->getXthWeekdayOfYear(1, "monday"); // will return a qCal_Date object for January 4th, 2010 $last_monday_of_the_year = $date->getXthWeekdayOfYear(-1, "monday"); // will return a qCal_Date object for December 27th, 2010 $thirtieth_sunday_of_the_year = $date->getXthWeekdayOfYear(30, 0); // will return a qCal_Date object for July 25th, 2010 $thirtieth_sunday_of_the_year = $date->getXthWeekdayOfYear(30, "sunday"); // the previous example could also be done like this $tenth_monday_of_2012 = $date->getXthWeekdayOfYear(10, "monday", 2012); // will return a qCal_Date object for March 5th, 2012
Returns a qCal_Date object representing the first day of the object's month.
qCal_Date getFirstDayOfMonth( void )
$date = new qCal_Date(2010, 1, 10); $first = $date->getFirstDayOfMonth(); // will return a qCal_Date object for January 1st, 2010
Returns a qCal_Date object representing the last day of the object's month.
qCal_Date getLastDayOfMonth( void )
$date = new qCal_Date(2010, 1, 10); $last = $date->getLastDayOfMonth(); // will return a qCal_Date object for January 31st, 2010
qCal_Date has many getters, but because it is immutable, there are no setters.
Returns the month as an integer from 1, meaning January to 12, meaning December.
Returns the month as a string such as January.
Returns the day as an integer from 1 to 31.
Returns the day as an integer from 0 to 365.
Returns the number of days until the end of the year, so if the date is December 25th, it will return “6”.
Returns the number of months until the end of the year, so if the date is in January, it will return “11”.
Returns the number of days in the year. This will return 365 unless it is a leap-year, when it will return 366.
Returns the number of days until the end of the month. So if the date is January 10th, 2010, it will return “21”.
Returns the year, so if the date is January 10th, 2010, it returns “2010”.
Returns the weekday as an integer from 0 (for Sunday) through 6 (for Saturday).
Returns the weekday as a string. So if the date is January 10th, 2010, it will return “Sunday”.
Returns the total days in the month, which will be an integer from 28 to 31.
Returns the current week of the year (with weeks starting on Monday) with leading zeros. If the date is January 11th, 2010, it will return “02”. This method is still in progress and may be a bit buggy. For now, I'd avoid it.
Returns the amount of weeks until the end of the year (with weeks starting on Monday). If the date is January 11th, 2010, it will return “50”. This method is still in progress and may be a bit buggy. For now, I'd avoid it.
Returns true if the date is within a leap-year, false otherwise.
Returns the current date as a unix timestamp.