DateTime

The date/time class.

This class can be used to manage date and time values and perform date arithmetic.

Example

$date = new Hazaar\Util\DateTime('next tuesday');
echo $date; //Echo's a timestamp such as '2013-01-15 11:00:00.0'

Timezones

It is possible to set the timezone globally for all date/time functions and classes.

For example, to set your timezone to 'Australia/ACT', in your application.ini file add the line:

pre. php.date.timezone = Australia/ACT

See the PHP Manual for a list of valid timezones.

If a timezone is not set in the application.ini file, nor is one set in the global PHP configuration then as a last ditch effort the Date class will default to UTC. This is because not having an ini setting in date.timzone will cause a PHP runtime error.

Properties

usec

public int $usec

dateFormat

Global format for date part.

public string $dateFormat = 'Y-m-d'

timeFormat

Global format for time part.

public string $timeFormat = 'H:i:s'

defaultFormat

public string $defaultFormat = 'l, F jS Y \a\t g:ia'

instanceFormat

private string $instanceFormat

Methods

__construct

Date constructor.

public __construct(mixed $datetime, string $timezone): void

The Date class constructor takes two values. A datetime declaration and a timezone. Both are optional. If now datetime is specified then the current datetime is used. If no timezone is specified then the default timezone will be used.

See the PHP documentation on strtotime() for more information on valid date time formats. If the datetime value is not set, the current date and time will be used. They can be either an integer representing the datetime Epoch value (seconds since 1970-01-01) or a string datetime description supported by the PHP strtotime() function. This means that textual datetime descriptions such as 'now' and 'next monday' will work.

Parameters

Parameter	Type	Description
$datetime	mixed	the datetime value you want to work with
$timezone	string	The timezone for this datetime value. If no timezone is specified then the default timezone is used.

__toString

Magic method to output the datetime value as a string.

public __toString(): void

Uses the Date::timestamp() method.

__export

public __export(): int

setFormat

public setFormat(string $format): void

Parameters

Parameter	Type	Description
$format	string

setTimezone

Set the timezone for the date object.

public setTimezone(string $timezone): DateTime

Setting this will cause the date and time to be output using the specified timezone. If a timezone is not given then the default system timezone will be used. This is a good way to convert a date of another timezone into the current default system timezone.

Parameters

Parameter	Type	Description
$timezone	string	The timezone to set. This can be either a DateTimeZone object, a string representation of a timezone, an offset in the format hh:mm, or a numeric value of the timezone returned by timezone_identifiers_list(). If it is left null, then the default system timezone is used.

formatTZ

Return the date time value using a format string for a specified timezone.

public formatTZ(string $format, string $timezone = 'UTC'): void

Parameters

Parameter	Type	Description
$format	string	A standard date format string
$timezone	string	The timezone to use to convert the date time value

getSQLDate

Get the current datetime value as an SQL compliant formatted string.

public getSQLDate(): void

sec

Returns the current datetime value as epoch (seconds passed since 1970-01-01).

public sec(): void

usec

Return the microsecond part of the datetime value.

public usec(): void

This will more than likely always be 0 (zero) unless specified in the constructor.

date

Return the date part formatted by the global date format.

public date(): void

time

Return the time part formatted by the global time format.

public time(): void

datetime

Return the date and time.

public datetime(): void

This will use the global date and time formats and concatenate them together, separated by a space.

timestamp

Get the timestamp formatted as a string.

public timestamp(): void

This will use the global date and time formats and concatenate them together, separated by a space.

age

Returns the age in years of the date with optional precision.

public age(int $precision): int

Parameters

Parameter	Type	Description
$precision	int	The number of digits to round an age to. Default: 0

diffSeconds

Returns the difference between the current date/time value and the value supplied as the first argument.

public diffSeconds(\DateTimeInterface $timestamp): int

Normally this method will return a \DateInterval object which is the default for the \DateTime class. However this functionality has been extended with the $returnSeconds parameter which will instead return an integer value indicating the difference in whole seconds.

Parameters

Parameter	Type	Description
$timestamp	\DateTimeInterface	The timestamp to compare the current date/time to

year

Returns the objects current year.

public year(): int

month

Returns the objects current month.

public month(): int

day

Returns the objects current day.

public day(): int

hour

Returns the objects current hour(.

public hour(): int

minute

Returns the objects current minute.

public minute(): int

second

Returns the objects current second.

public second(): int

add

Add a date/time interval to the current date/time.

public add(string $interval, boolean $returnNew): void

See the PHP documentation on how to use the DateInterval object.

Parameters

Parameter	Type	Description
$interval	string	Can be either a \DateInterval object or a string representing an interval, such as P1H to specify 1 hour
$returnNew	boolean	Doesn't update the current \Hazaar\Util\DateTime object and instead returns a new object with the interval applied

sub

Subtract a date/time interval from the current date/time.

public sub(string $interval, bool $returnNew): void

See the PHP documentation on how to use the DateInterval object.

Parameters

Parameter	Type	Description
$interval	string	can be either a \DateInterval object or a string representing an interval, such as P1H to specify 1 hour
$returnNew	bool	doesn't update the current \Hazaar\Util\DateTime object and instead returns a new object with the interval applied

compare

Compare the current date with the argument.

public compare(mixed $date, bool $includeTime): bool

Parameters

Parameter	Type	Description
$date	mixed
$includeTime	bool

start

Returns the start time of the current date as a Date object.

public start(): DateTime

end

Returns the end time of the current date as a Date object.

public end(): DateTime

firstOfWeek

Returns the first day of the current week as a Date object.

public firstOfWeek(): DateTime

lastOfWeek

Returns the last day of the current week as a Date object.

public lastOfWeek(): DateTime

firstOfMonth

Returns the first day of the current month as a Date object.

public firstOfMonth(): DateTime

firstOfYear

Returns the first day of the current year as a Date object.

public firstOfYear(): DateTime

lastOfYear

Returns the last day of the current year as a Date object.

public lastOfYear(): DateTime

getFuzzyDiff

Return a fuzzy diff between the current time and the Date value.

public getFuzzyDiff(bool $precise, int $dateThresholdDays = 30): string

Parameters

Parameter	Type	Description
$precise	bool	Boolean indicating if precise mode should be used. This generally adds the time to day-based results.
$dateThresholdDays	int	A threshold in days after which the full date will be returned. Avoids situations like "3213 days ago" which is silly.

getLocaleData

Get locale data for a specified locale.

public getLocaleData(string $locale, bool $): void

Data included is what is returned by PHP's localeconv() function.

Parameters

Parameter	Type	Description
$locale	string	the locale to get data for
$	bool

getLocaleDateFormat

Retrieve a date format for a specific locale.

public getLocaleDateFormat(string $locale): string

This will return something like DMY to indicate that the locale format is date, month followed by year.

These formats are not meant to be used directly in date functions as different date functions use different format specifiers and we won't even attempt to support all of them here.

Parameters

Parameter	Type	Description
$locale	string

jsonSerialize

Outputs the UTC timestamp (EPOCH) When an object is included in a json_encode call.

public jsonSerialize(): mixed

ftime

Hazaar implementation of the str_ftime function.

public ftime(string $format, ?int $timestamp): string

This function is a replacement for the deprecated strftime function. It is not a complete replacement but it does provide a lot of the functionality that strftime does. It is not a drop-in replacement for strftime as it does not support all the same format specifiers.

The following format specifiers are supported:

• %a An abbreviated textual representation of the day Sun through Sat
• %A A full textual representation of the day Sunday through Saturday
• %d Two-digit day of the month (with leading zeros) 01 to 31
• %e Day of the month, with a space preceding single digits. Not implemented as described on Windows. See below for more information. 1 to 31
• %j Day of the year, 3 digits with leading zeros 001 to 366
• %u ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
• %w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
• %U Week number of the given year, starting with the first Sunday as the first week 13 (for the 13th full week of the year)
• %V ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week 01 through 53 (where 53 accounts for an overlapping week)
• %W A numeric representation of the week of the year, starting with the first Monday as the first week 46 (for the 46th week of the year beginning with a Monday)
• %b Abbreviated month name, based on the locale Jan through Dec
• %B Full month name, based on the locale January through December
• %h Abbreviated month name, based on the locale (an alias of %b) Jan through Dec
• %m Two digit representation of the month 01 (for January) through 12 (for December)
• %C Two digit representation of the century (year divided by 100, truncated to an integer) 19 for the 20th Century
• %g Two digit representation of the year going by ISO-8601:1988 standards (see %V) Example: 09 for the week of January 6, 2009
• %G The full four-digit version of %g Example: 2008 for the week of January 3, 2009
• %y Two digit representation of the year Example: 09 for 2009, 79 for 1979
• %Y Four digit representation for the year Example: 2038
• %H Two digit representation of the hour in 24-hour format 00 through 23
• %k Hour in 24-hour format, with a space preceding single digits 0 through 23
• %I Two digit representation of the hour in 12-hour format 01 through 12
• %l (lower-case 'L') Hour in 12-hour format, with a space preceding single digits 1 through 12
• %M Two digit representation of the minute 00 through 59
• %p UPPER-CASE 'AM' or 'PM' based on the given time Example: AM for 00:31, PM for 22:23
• %P lower-case 'am' or 'pm' based on the given time Example: am for 00:31, pm for 22:23
• %r Same as "%I:%M:%S %p" Example: 09:34:17 PM for 21:34:17
• %R Same as "%H:%M" Example: 00:35 for 12:35 AM, 16:44 for 4:44 PM
• %S Two digit representation of the second 00 through 59
• %T Same as "%H:%M:%S" Example: 21:34:17 for 09:34:17 PM
• %X Preferred time representation based on locale, without the date Example: 03:59:16 or 15:59:16
• %z The time zone offset. Not implemented as described on Windows. See below for more information. Example: -0500 for U.S. Eastern Time
• %Z Time zone name. Not implemented as described on Windows. See below for more information. Example: EST for Eastern Time
• %s The number of seconds since the Unix Epoch Example: 1390948122
• %n A newline character ("\n")
• %t A Tab character ("\t")
• %% A literal percentage character ("%")

Parameters

Parameter	Type	Description
$format	string	The format string to use defined by the original strftime() function
$timestamp	int

---

Generated by Hazaar API Doc Generator