qCal_Time

Times in qCal are represented by the qCal_Time object (naturally). qCal_Time is immutable, meaning once you instantiate it, there is no way to change the time it represents. So if you need a new time, create a new object.

new qCal_Time( [int $hour [, int $minute [, int $second [, mixed $timezone [, bool $rollover ]]]]] )

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 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 qCal_Time object will represent 2:05.

The default value is false.

$time = new qCal_Time(10, 30, 0, "GMT"); // will result in an object for 10:30:00am GMT
$time = new qCal_Time(23, 0, 0, new qCal_Timezone("Custom_Timezone", -3600)); // will result in an object for 11:00:00pm with a custom timezone
$time = new qCal_Time(5, 70, 0, null, true); // will result in 6:10:00 using the server's default timezone

You can also generate a qCal_Time object from a string such as “5:00pm” or “23:00” 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 date portion of the string will be ignored).

qCal_Time qCal_Time::factory(string $time [, mixed $timezone])

The time parameter should be a string representing a specific time.

The timezone parameter can be either a qCal_Timezone object or a string representing any valid timezone identifier.

Defaults to the server's default timezone.

$time1 = qCal_Time::factory("4:00"); // will result in 4:00am using the server's timezone
$time2 = qCal_Time::factory("now", "America/Los_Angeles"); // will result in the current time in America/Los_Angeles

qCal_Time implement's PHP's magic __toString() method, which allows you to simply print it out to get a human-readable time.

$time = new qCal_Time(4, 0, 0);
echo $time; // will output "04:00:00"

If you need the string output in a different format, use the qCal_Time::setFormat() method. All subsequent calls to __toString() (basically any time you print out the object) will output using the format you specified. qCal_Time::setFormat() accepts the following time-related metacharacters defined by PHP's date() function: 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.

$time = new qCal_Time(15, 30, 30);
$time->setFormat("g:ia");
echo $time; // outputs "3:30pm"
 
$time->setFormat("H"); 
echo $time; // outputs "15"

If you need to convert the time to a string, but don't need to print it out, call qCal_Time::format(). Calling this method will not change the way the object prints like qCal_Time::setFormat() does.

$time = new qCal_Time(6, 30, 0);
$string = $time->format("H:i");
echo $time; // still outputs "06:30:00" because we did not call setFormat()
echo $string; // outputs "06:30"

Returns the timezone as a qCal_Timezone object.

Returns the hour in 24-hour format without leading zeroes.

Returns the minutes, which will be between 0 and 59.

Returns the seconds, which will be between 0 and 59.