<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fTimestamp">Class Documentation</a>''' - <a href="/api/fTimestamp">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fTimestamp.php" target="_blank">Source Code</a>
<<toc></toc>>
- fDate - fTime - '''fTimestamp'''
- fDate - fMoney - fNumber - fTime - '''fTimestamp'''
)))
The fTimestamp class is a value object representation of a date/time. One of the primary attributes of the object is that its value can not be changed, but instead a new object is created. This object has full support for timezones.
This class is built on top of the PHP date/time functions and can only handle dates ranging from 1901–2038.
The fTimestamp class is fully compatible with timezones thanks the the great changes in PHP 5.1. Classically timezones were represented by short abbreviations such as `EST`, `GMT`, `PST`, etc. To help remove abiguity, PHP now recommends using the zoneinfo timezone names.
Due to the revamped timezone support in PHP 5.1, it is now necessary to define the default timezone. This is done to ensure the proper timezone is being used and also prevent strict error reporting messages from appearing. fTimestamp provides two methods for setting and getting the default timezone, ::setDefaultTimezone() and ::getDefaultTimezone().
There will be more timezone discussion throughout the rest of this document in the relevant places.
The fTimestamp constructor takes two parameters, including `$datetime` and `$timezone`. `$datetime` is a string, object (with a `__toString()` method) or integer representing a date/time. For strings and objects, any format accepted by `strtotime()` will work. Integers are interpreted as a unix timestamp. `$timezone` is optional and if passed should be a string with a zoneinfo timezone name. This timezone will be used throughout the life of the timestamp.
Rather than allowing an fTimestamp object value to be modified, which can create issues since objects are passed by reference, all changes to a timestamp create a new object.
Usually when modifying a timestamp, only one or two components (such as month, year, hour or minute) of the timestamp will change. The ::modify() method leverages the formatting codes from the `date()` function to keep parts of the existing timestamp while replacing others.
Here are some examples of `modify()`:
It is also possible to set the timezone of the new timestamp. The timezone can be passed as the optional second parameter to `modify()`. If no timezone is specified, the new timestamp will have the same timezone as the original.
Occasionally you may have the need to adjust a timestamp. The ::adjust() method takes a single parameter which can contain any relative time measurement that `strtotime()` accepts. Since fTimestamp is a value object, a new object is returned with the adjusted value. Here are some examples:
Adjustments can also be adjustments of timezone. If a valid timezone is passed, the actual date/time will not be changed, however the date/time will appear different from ::format().
To format the timestamp, simply call the ::format() method with any valid formatting string from `date()`. Here are some examples:
When dealing with date across a site or application, it is easy to create inconsistent formatting. In an effort to encourage consistency and at the same time prevent the need to clutter the global namespace with constants, the ::defineFormat() static method allows for creating named formats for use with the ::format() method and the method fTime::format() and fDate::format().
Definition of the formats would logically go in a configuration file. `defineFormat()` takes two parameters, the `$name` and the `$formatting_string`.
Once defined, the format names can be passed into the `format()` method of fDate, fTime and fTimestamp.
There are five different methods available to compare timestamps, ::eq(), ::gt(), ::gte(), ::lt() and ::lte(). Each method optionally accepts a parameter `$other_timestamp`. If no `$other_timestamp` is specified, the timestamp is compared to the current timestamp. If `$other_timestamp` is specified, the two are compared. `$other_timestamp` accepts any valid date string that works with ::__construct().
Here are some examples:
If you are looking to get a fuzzy difference between two timestamps for display, you’ll want to use the ::getFuzzyDifference() method. The first parameter, `$other_timestamp`, optionally accepts a valid timestamp descriptor that can be passed to ::__construct(). If a valid timestamp descriptor is passed, the difference will be between the two timestamps, if nothing is passed, the difference will be between the fTimestamp and the current timestamp.
The value returned by `getFuzzyDifference()` will be a string representing the most broad time measurement between the two timestamps. In addition, if the difference is just shy of the next largest time measurement, it will be rounded up. Thus 3.5 weeks would become 1 month.
Here are some examples to clarify. The following examples are comparing two timestamps:
These examples show output when comparing an fTimestamp object with the current timestamp:
An optional boolean parameter, `$simple`, can also be passed to `getFuzzyDifference()`. When `TRUE`, this parameter causes the method to return the difference in time, but not the direction.
PHP contains built-in support for formatting date and times in different languages via the `setlocale()` function. This function, however, has a number of shortcomings including it requiring a non-threaded web server and requiring that locale files be installed for each locale to support.
The fTimestamp class provides a hook for formatting fDate, fTime and fTimestamp objects in whatever fashion is necessary. A callback can be assigned to the hook by passing it to the static method ::registerFormatCallback(). The callback should accept a single string and return a single string.
It is also possible to parse locale-specific date/time/timestamp strings by passing a callback to ::registerUnformatCallback(). The callback should accept a string and return a string that will properly be parsed by `strtotime()`. An example of a valid return string would be `2009-05-01 15:22:01`.
Below is an example of how the hooks could be used.