The qCal_DateTime object is basically just an aggregation of qCal_Date and qCal_Time with a few extra convenience methods.
new qCal_Time( [ int $year [, int $month [, int $day [, int $hour [, int $minute [, int $second [, mixed $timezone [, 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.
The hour must be specified in 24-hour time format. So if you need 2pm, you need to specify 14 as the hour.
The default value is the current hour (in whatever timezone you specify).
Minute can be any value from 0 to 59.
The default value is the current minute (in whatever timezone you specify).
Second can be any value from 0 to 59.
The default value is the current second.
Timezone can be either a qCal_Timezone object, or a string representing any of PHP's pre-defined timezones.
If set to true, the month, day, hour, minute and second parameters can be more or less than their normally allowed values, resulting in a rollover. For instance, if hour is specified as 1 and minute is specified as 65, the resulting time will be 2:05.
The default value is false.
You can also generate a qCal_DateTime object from a string such as “January 1st, 2010 at 3pm” by using the static “factory” method. Most values that can be passed to PHP's strtotime function can be passed to the factory method.
qCal_Date qCal_DateTime::factory( string $datetime [, mixed $timezone ] )
The datetime parameter can be either a string representing a specific date and time, or a unix timestamp.
The timezone parameter can be either a valid PHP timezone identifier string, or a qCal_Timezone object.
$datetime1 = qCal_DateTime::factory("January 21st, 2010 3pm"); $datetime2 = qCal_DateTime::factory("noon tomorrow"); // will result in whatever tomorrow's date is and at noon $datetime3 = qCal_DateTime::factory("now"); // will result in today's date and time $datetime4 = qCal_DateTime::factory(time()); // will result in today's date and time $datetime5 = qCal_DateTime::factory("October 1st, 2009 9am", "America/Los_Angeles"); // will result in October 1st, 2009 at 9am in America/Los_Angeles time
qCal_DateTime implement's PHP's magic __toString() method, which allows you to simply print it out to get a human-readable date/time.
$datetime = new qCal_DateTime(2010, 1, 12, 4, 30, 0, "America/Los_Angeles"); echo $datetime; // will output "2010-01-12T04:30:00-08:00"
If you need the string output in a different format, use the qCal_DateTime::setFormat() method. All subsequent calls to __toString() (basically any time you print out the object) will output using the format you specified. qCal_DateTime::setFormat() accepts the following metacharacters defined 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, U, a, A, B, g, G, h, H, i, s, 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.
$datetime = new qCal_DateTime(2010, 12, 10, 15, 30, 0, "GMT"); $datetime->setFormat('m/d/Y \a\t g:ia'); echo $datetime; // outputs "12/10/2010 at 3:30pm" $datetime->setFormat("H"); echo $datetime; // outputs "15"
If you need to convert the object to a string, but don't need to print it out, call qCal_DateTime::format(). Calling this method will not change the way the object prints like qCal_DateTime::setFormat() does.
$datetime = new qCal_DateTime(2010, 11, 10, 6, 30, 0, "GMT"); $string = $datetime->format("H:i"); echo $datetime; // still outputs "2010-11-10T06:30:00+00:00" because we did not call setFormat() echo $string; // outputs "06:30"
Often when dealing with dates and times, especially within the context of iCalendar, it is necessary to get the date/time in UTC format. If you are not familiar with UTC, you can find out everything you need to know about it in the Wikipedia article for UTC.
Coordinated Universal Time (UTC) is a time standard based on International Atomic Time (TAI) with leap seconds added at irregular intervals to compensate for the Earth's slowing rotation. Leap seconds are used to allow UTC to closely track UT1, which is mean solar time at the Royal Observatory, Greenwich.
The difference between UTC and UT1 is not allowed to exceed 0.9 seconds, so if high precision is not required the general term Universal Time (UT) may be used.
In casual use, when fractions of a second are not important, Greenwich Mean Time (GMT) can be considered equivalent to UTC or UT1. Owing to the ambiguity as to whether UTC or UT1 is meant, GMT is generally avoided in technical contexts.
Time zones around the world can be expressed as positive or negative offsets from UTC; UTC replaced GMT as the basis for the main reference time scale or civil time in various regions on 1 January 1972.
Coordinated Universal Time, Wikipedia.org http://en.wikipedia.org/wiki/Coordinated_Universal_Time
This method is used to convert a qCal_DateTime object to a UTC string.
string qCal_Date::getUtc( [bool $humanReadable] )
If set to true, the resulting UTC string will be a more human-readable format than the default return value.
Defaults to false.
$datetime = new qCal_DateTime(2009, 10, 31, 10, 30, 0, "America/Los_Angeles"); $utc = $datetime->getUtc(); // returns "20091031T183000Z" $utcHumanReadable = $datetime->getUtc(true); // returns "2009-10-31T18:30:00Z"
Because qCal_DateTime is mainly just an aggregation of qCal_Date and qCal_Time, I have not duplicated their functionality in this class. If you need a method such as “getYear()”, use $datetime->getDate()->getYear(). If you need something like “getHour()”, use $datetime->getTime()->getHour().
Returns the time portion of the object as a qCal_Time object.
Returns the date portion of the object as a qCal_Date object.