qCal_Timezone

Because qCal works independently of PHP's built-in timezone functionality, a qCal_Timezone class was necessary. Any time you need to work with time in qCal, there will be a qCal_Timezone associated with it. In classes that require a timezone, the qCal_Timezone object defaults to whatever the server's default timezone is, but if you want to specify a different and/or custom timezone, you will need to use this class.

new qCal_Timezone( string $name, int $offset [, string $abbreviation [, bool $daylightsavings ]] )

The full name of the timezone you are creating. For instance, the name for my timezone would be “America/Los_Angeles”.

The offset represents the offset (in seconds) from UTC this timezone represents.

Most timezones have an abbreviated version of their name. For instance, “Greenwich Mean Time” is abbreviated to “GMT”.

If no abbreviation is specified, the full name will be used.

Set this to true if the timezone observes daylight savings time.

This parameter defaults to false.

NOTE: This parameter is not fully implemented yet, and I do not advise using it until it is.

// GMT has no offset
$gmt = new qCal_Timezone("Greenwich Mean Time", 0, "GMT");
 
// America/Los_Angeles is 8 hours behind UTC, so the offset will be -8 * 60 seconds times 60 minutes (-28800)
$la = new qCal_Timezone("America/Los_Angeles", -28800); 
 
// Eastern Standard Time is five hours behind UTC and is abbreviated as EST
$eastern = new qCal_Timezone("Eastern Standard Time", -18000, "EST");
 
// You can also create completely custom timezones. This one represents UTC + 1 hour and observes daylight savings.
$custom = new qCal_Timezone("Lukes Time Zone", 3600, "LTZ", true);

If you need to create a qCal_Timezone object for one of PHP's pre-defined timezones, it is much easier to use the factory method than it is to instantiate one directly.

qCal_Timezone qCal_Timezone::factory( [ string $timezone ] )

The timezone parameter must be one of PHP's pre-defined timezone identifiers.

Defaults to the server's default timezone.

$gmt = qCal_Timezone::factory("GMT"); // will result in Greenwich Mean Time
$la = qCal_Timezone::factory("America/Los_Angeles"); // will result in timezone for America/Los_Angeles, which is eight hours behind UTC
$eastern = qCal_Timezone::factory("US/Eastern"); // will result in the timezone for Eastern Standard Time, which is five hours behind UTC
$defaultTZ = qCal_Timezone::factory(); // will result in whatever timezone your server is currently set to

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

$tz = new qCal_Timezone("America/Los_Angeles", -28800);
echo $tz; // will output "America/Los_Angeles"

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

$tz = new qCal_Timezone("America/Los_Angeles", -28800, "PST");
$tz->setFormat("T P");
echo $tz; // outputs "PST -08:00"
 
$tz->setFormat("Z"); 
echo $time; // outputs "-28800"

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

$tz = new qCal_Timezone("America/Los_Angeles", -28800, "PST");
$string = $tz->format("T P");
echo $tz; // still outputs "America/Los_Angeles" because we did not call setFormat()
echo $string; // outputs "PST -08:00"

qCal_Timezone comes with a few simple getters for retrieving simple information about the timezone such as its abbreviation, offset in seconds, etc.

Returns the full name of the timezone.

Returns the timezone offset in hours. If the timezone's offset is -28800, this method will return ”-08:00”.

Returns the timezone offset in hours. If the timezone's offset is -28800, this method will return ”-0800”.

Returns the timezone offset in seconds.

Returns the abbreviated form of the timezone name.

Returns true if the timezone observes daylight savings time, false otherwise.

NOTE: The daylight savings functionality is not fully implemented yet, so use them at your own risk.