Flourish PHP Unframework

fTimestamp

Class Resources

Variables

Static Methods

Methods

Uses

Used By

class, v1.0.0b13

Represents a date and time as a value object

Changes:
1.0.0b13Fixed a method signature 8/24/11
1.0.0b12Fixed a bug with the constructor not properly handling unix timestamps that are negative integers 6/2/11
1.0.0b11Changed the $timestamp and $timezone attributes to be protected 3/20/11
1.0.0b10Fixed a bug in __construct() with specifying a timezone other than the default for a relative time string such as "now" or "+2 hours" 7/5/10
1.0.0b9Added the $simple parameter to getFuzzyDifference() 3/15/10
1.0.0b8Fixed a bug with fixISOWeek() not properly parsing some ISO week dates 10/6/09
1.0.0b7Fixed a translation bug with getFuzzyDifference() 7/11/09
1.0.0b6Added registerUnformatCallback() and callUnformatCallback() to allow for localization of date/time parsing 6/1/09
1.0.0b5Backwards compatibility break - Removed getSecondsDifference() and getSeconds(), added eq(), gt(), gte(), lt(), lte() 3/5/09
1.0.0b4Updated for new fCore API 2/16/09
1.0.0b3Removed a useless double check of the strtotime() return value in __construct() 1/21/09
1.0.0b2Added support for CURRENT_TIMESTAMP, CURRENT_DATE and CURRENT_TIME SQL keywords 1/11/09
1.0.0bThe initial implementation 2/12/08

Variables

->timestamp protected

The date/time

Type

integer

->timezone protected

The timezone for this date/time

Type

string

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'

Signatures

string getFuzzyDifference( fTimestamp|object|string|integer $other_timestamp=NULL, boolean $simple=FALSE )

string getFuzzyDifference( boolean $simple=FALSE )

Parameters

fTimestamp|object|string|integer $other_timestamp The timestamp to create the difference with, NULL is interpreted as now
boolean $simple When TRUE, the returned value will only include the difference in the two timestamps, but not from now, ago, after or before

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