fTimestampclassv1.0.0b8
Represents a date and time as a value object
| 1.0.0b8 | Fixed a bug with fixISOWeek() not properly parsing some ISO week dates 10/6/09 |
|---|---|
| 1.0.0b7 | Fixed a translation bug with getFuzzyDifference() 7/11/09 |
| 1.0.0b6 | Added registerUnformatCallback() and callUnformatCallback() to allow for localization of date/time parsing 6/1/09 |
| 1.0.0b5 | Backwards compatibility break - Removed getSecondsDifference() and getSeconds(), added eq(), gt(), gte(), lt(), lte() 3/5/09 |
| 1.0.0b4 | Updated for new fCore API 2/16/09 |
| 1.0.0b3 | Removed a useless double check of the strtotime() return value in __construct() 1/21/09 |
| 1.0.0b2 | Added support for CURRENT_TIMESTAMP, CURRENT_DATE and CURRENT_TIME SQL keywords 1/11/09 |
| 1.0.0b | The initial implementation 2/12/08 |
Static Methods
::callFormatCallback() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
If a format callback is defined, call it
Signature
string callFormatCallback( string $formatted_string )
Parameters
| string | $formatted_string | The formatted date/time/timestamp string to be (possibly) modified |
Returns
The (possibly) modified formatted string
::callUnformatCallback() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
If an unformat callback is defined, call it
Signature
string callUnformatCallback( string $date_time_string )
Parameters
| string | $date_time_string | A raw date/time/timestamp string to be (possibly) parsed/modified |
Returns
The (possibly) parsed or modified date/time/timestamp
::compose() protected
Composes text using fText if loaded
Signature
string compose( string $message, mixed $component )
Parameters
| string | $message | The message to compose |
| mixed | $component [, ... ] | A string or number to insert into the message |
Returns
The composed and possible translated message
::defineFormat() public
Creates a reusable format for formatting fDate, fTime, and fTimestamp objects
Signature
void defineFormat( string $name, string $formatting_string )
Parameters
| string | $name | The name of the format |
| string | $formatting_string | The format string compatible with the date() function |
::fixISOWeek() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Fixes an ISO week format into 'Y-m-d' so strtotime() will accept it
Signature
string fixISOWeek( string $date )
Parameters
| string | $date | The date to fix |
Returns
The fixed date
::getDefaultTimezone() public
Provides a consistent interface to getting the default timezone. Wraps the date_default_timezone_get() function.
Signature
string getDefaultTimezone( )
Returns
The default timezone used for all date/time calculations
::isValidTimezone() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Checks to see if a timezone is valid
Signature
boolean isValidTimezone( string $timezone )
Parameters
| string | $timezone | The timezone to check |
Returns
If the timezone is valid
::registerFormatCallback() public
Allows setting a callback to translate or modify any return values from format(), fDateformat() and fTime::format()
Signature
void registerFormatCallback( callback $callback )
Parameters
| callback | $callback | The callback to pass all formatted dates/times/timestamps through. Should accept a single string and return a single string. |
::registerUnformatCallback() public
Allows setting a callback to parse any date strings passed into __construct(), fDate__construct() and fTime::__construct()
Signature
void registerUnformatCallback( callback $callback )
Parameters
| callback | $callback | The callback to pass all date/time/timestamp strings through. Should accept a single string and return a single string that is parsable by strtotime(). |
::reset() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Resets the configuration of the class
Signature
void reset( )
::setDefaultTimezone() public
Provides a consistent interface to setting the default timezone. Wraps the date_default_timezone_set() function.
Signature
void setDefaultTimezone( string $timezone )
Parameters
| string | $timezone | The default timezone to use for all date/time calculations |
::translateFormat() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Takes a format name set via defineFormat() and returns the date() function formatting string
Signature
string translateFormat( string $format )
Parameters
| string | $format | The format to translate |
Returns
The formatting string. If no matching format was found, this will be the same as the $format parameter.
Methods
->__construct() public
Creates the date/time to represent
Signature
fTimestamp __construct( fTimestamp|object|string|integer $datetime=NULL, string $timezone=NULL )
Parameters
| fTimestamp|object|string|integer | $datetime | The date/time to represent, NULL is interpreted as now |
| string | $timezone | The timezone for the date/time. This causes the date/time to be interpretted as being in the specified timezone. If not specified, will default to timezone set by setDefaultTimezone(). |
Throws
- fValidationException
- When $datetime is not a valid date/time, date or time value
->__get() internal public
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
All requests that hit this method should be requests for callbacks
Signature
callback __get( string $method )
Parameters
| string | $method | The method to create a callback for |
Returns
The callback for the method requested
->__toString() public
Returns this date/time
Signature
string __toString( )
Returns
The 'Y-m-d H:i:s' format of this date/time
->adjust() public
Changes the date/time by the adjustment specified
Signature
fTimestamp adjust( string $adjustment )
Parameters
| string | $adjustment | The adjustment to make - may be a relative adjustment or a different timezone |
Returns
The adjusted date/time
Throws
- fValidationException
- When $adjustment is not a valid relative date/time measurement or timezone
->eq() public
If this timestamp is equal to the timestamp passed
Signature
boolean eq( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to compare with, NULL is interpreted as today |
Returns
If this timestamp is equal to the one passed
->format() public
Formats the date/time
Signature
string format( string $format )
Parameters
| string | $format | The date() function compatible formatting string, or a format name from defineFormat() |
Returns
The formatted date/time
->getFuzzyDifference() public
Returns the approximate difference in time, discarding any unit of measure but the least specific.
The output will read like:
- "This timestamp is {return value} the provided one" when a timestamp it passed
- "This timestamp is {return value}" when no timestamp is passed and comparing with the current timestamp
Examples of output for a timestamp passed might be:
- '5 minutes after'
- '2 hours before'
- '2 days after'
- 'at the same time'
Examples of output for no timestamp passed might be:
- '5 minutes ago'
- '2 hours ago'
- '2 days from now'
- '1 year ago'
- 'right now'
You would never get the following output since it includes more than one unit of time measurement:
- '5 minutes and 28 seconds'
- '3 weeks, 1 day and 4 hours'
Values that are close to the next largest unit of measure will be rounded up:
- '55 minutes' would be represented as '1 hour', however '45 minutes' would not
- '29 days' would be represented as '1 month', but '21 days' would be shown as '3 weeks'
Signature
string getFuzzyDifference( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to create the difference with, NULL is interpreted as now |
Returns
The fuzzy difference in time between the this timestamp and the one provided
->gt() public
If this timestamp is greater than the timestamp passed
Signature
boolean gt( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to compare with, NULL is interpreted as now |
Returns
If this timestamp is greater than the one passed
->gte() public
If this timestamp is greater than or equal to the timestamp passed
Signature
boolean gte( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to compare with, NULL is interpreted as now |
Returns
If this timestamp is greater than or equal to the one passed
->lt() public
If this timestamp is less than the timestamp passed
Signature
boolean lt( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to compare with, NULL is interpreted as today |
Returns
If this timestamp is less than the one passed
->lte() public
If this timestamp is less than or equal to the timestamp passed
Signature
boolean lte( fTimestamp|object|string|integer $other_timestamp=NULL )
Parameters
| fTimestamp|object|string|integer | $other_timestamp | The timestamp to compare with, NULL is interpreted as today |
Returns
If this timestamp is less than or equal to the one passed
->modify() public
Modifies the current timestamp, creating a new fTimestamp object
The purpose of this method is to allow for easy creation of a timestamp based on this timestamp. Below are some examples of formats to modify the current timestamp:
- 'Y-m-01 H:i:s' to change the date of the timestamp to the first of the month:
- 'Y-m-t H:i:s' to change the date of the timestamp to the last of the month:
- 'Y-m-d 17:i:s' to set the hour of the timestamp to 5 PM:
Signature
fTimestamp modify( string $format, string $timezone=NULL )
Parameters
| string | $format | The current timestamp will be formatted with this string, and the output used to create a new object. The format should not include the timezone (character e). |
| string | $timezone | The timezone for the new object if different from the current timezone |
Returns
The new timestamp
