DateTimeObject

date and time format object abstraction based on ISO 8601 standard

package

Default

Methods

Object that represents a date and time value and its related operations.

__construct(string $dateTimeString = '') : \org\turbocommons\src\main\php\model\DateTimeObject

All the class methods are based and expect values that follow the ISO 8601 format, which is the international standard for the representation of dates and times. Any other date/time format will be considered as invalid.

Following is an example of a valid ISO 8601 dateTime value:

yyyy-mm-ddTHH:MM:SS.UUU+TT:TT

where:

  • yyyy is a four digits year value
  • mm is a two digits month value
  • dd is a two digits day value
  • HH is a two digits hour value
  • MM is a two digits minutes value
  • SS is a two digits seconds value
  • UUU is an arbitrary number of digits decimal seconds fraction value
  • +TT:TT is the timezone offset value, like +03:00
example

Will create a DateTimeObject with the value '1996-01-01T00:00:00.000000+XX:XX' based on the current system defined timezone

Will create a DateTimeObject with the value '1996-12-01T00:00:00.000000+XX:XX' based on the current system defined timezone

is a fully valid ISO 8601 string value: '2017-10-14T17:55:25.163583+02:00'

see https://es.wikipedia.org/wiki/ISO_8601

Arguments

$dateTimeString

string

A string containing a valid ISO 8601 date/time value that will be used to initialize this instance. If string is empty, the current system date/time and timezone will be used. If string is incomplete, all missing parts will be filled with the lowest possible value. If timezone offset is missing, the timezone that is currently defined on the system will be used.

Response

\org\turbocommons\src\main\php\model\DateTimeObject

The created instance

Adds the specified amount of time to the given dateTime value TODO - This method currently only works with years, and PHPDoc is incomplete!

add(string $value, string $type = 'minutes') : void

Arguments

$value

string

The numeric amount that will be added to this DateTimeObject instance

$type

string

TODO - this paramenter description

This method compares two dateTime values and tells if they are exactly the same or which one represents a later time value than the other.

compare(mixed $dateTime1, mixed $dateTime2) : integer
static

Timezones from the specified dateTime values are taken into consideration for the comparison.

Throws
\UnexpectedValueException

Arguments

$dateTime1

mixed

A valid ISO 8601 dateTime value or a DateTimeObject instance.

$dateTime2

mixed

A valid ISO 8601 dateTime value or a DateTimeObject instance.

Response

integer

0 If the two dateTime values represent the exact same time, 1 if dateTime1 > dateTime2 or 2 if dateTime2 > dateTime1

Compares the current datetime instance value to the given one and tells if they are exactly the same or which one represents a later time value than the other.

compareTo(mixed $dateTime) : integer

Timezones from the both dateTime values are taken into consideration for the comparison.

see \org\turbocommons\src\main\php\model\DateTimeObject::compare
Throws
\UnexpectedValueException

Arguments

$dateTime

mixed

A valid ISO 8601 dateTime value or a DateTimeObject instance.

Response

integer

0 If the two dateTime values represent the exact same time, 1 if this instance > dateTime or 2 if dateTime > this instance

Get the day based on current system date and timezone as a numeric value from 1 to 31

getCurrentDay() : integer
static

Response

integer

The day of month as a value between 1 and 31

Get the numeric day of week (between 1 and 7) based on current system time, where Sunday is considered to be the first one:<br> 1 = Sunday, 2 = Monday, 3 = Tuesday, etc .

getCurrentDayOfWeek() : integer
static

..

Response

integer

A numeric value between 1 and 7 (where Sunday is 1, Monday is 2, ...)

Get the hour based on current system date and timezone as a numeric value from 0 to 23

getCurrentHour() : integer
static

Response

integer

The hour as a value between 0 and 23

Get the microseconds based on current system date and timezone as a numeric value up to 6 digits

getCurrentMicroSecond() : integer
static

Response

integer

The microseconds as a value up to 6 digits

Get the miliseconds based on current system date and timezone as a numeric value up to 3 digits

getCurrentMiliSecond() : integer
static

Response

integer

The miliseconds as a value up to 3 digits

Get the minute based on current system date and timezone as a numeric value from 0 to 59

getCurrentMinute() : integer
static

Response

integer

The minute as a value between 0 and 59

Get the month based on current system date and timezone as a numeric value from 1 to 12

getCurrentMonth() : integer
static

Response

integer

A value between 1 and 12

Get the seconds based on current system date and timezone as a numeric value from 0 to 59

getCurrentSecond() : integer
static

Response

integer

The seconds as a value between 0 and 59

Get the timezone name based on current system date and timezone

getCurrentTimeZoneName() : string
static

Response

string

The timezone name

Get the timezone offset based on current system date and timezone as a numeric value (in seconds)

getCurrentTimeZoneOffset() : integer
static

Response

integer

The timezone offset as a numeric value in seconds

Get the year based on current system date and timezone

getCurrentYear() : integer
static

Response

integer

A numeric value representing the current year

Get this instance's defined day as a numeric value from 1 to 31

getDay() : integer

Response

integer

A value between 1 and 31

Get the english name representing the given numeric value of a week day (between 1 and 7), where Sunday is considered to be the first one: 1 = Sunday, 2 = Monday, 3 = Tuesday, etc .

getDayName(integer $day) : string
static

..

Arguments

$day

integer

A day number between 1 and 7

Response

string

The day name in english and with capital letters, like for example: MONDAY, SATURDAY...

Get this instance's defined day of week as a numeric value from 1 to 7, where Sunday is considered to be the first one:<br> 1 = Sunday, 2 = Monday, 3 = Tuesday, etc .

getDayOfWeek() : integer

..

Response

integer

A numeric value between 1 and 7

Get the first day of month for the current dateTime value.

getFirstDayOfMonth() : \org\turbocommons\src\main\php\model\DateTimeObject

Response

\org\turbocommons\src\main\php\model\DateTimeObject

A dateTime object representing the first day of month based on the current instance

Get this instance's defined hour as a numeric value from 0 to 23

getHour() : integer

Response

integer

A value between 0 and 23

Get the last day of month for the current dateTime value.

getLastDayOfMonth() : \org\turbocommons\src\main\php\model\DateTimeObject

Response

\org\turbocommons\src\main\php\model\DateTimeObject

A dateTime object representing the last day of month based on the current instance

Get this instance's defined microseconds as a numeric value up to 6 digit

getMicroSecond() : integer

Response

integer

A value up to 6 digit

Get this instance's defined miliseconds as a numeric value up to 3 digit

getMiliSecond() : integer

Response

integer

A value up to 3 digit

Get this instance's defined minute as a numeric value from 0 to 59

getMinute() : integer

Response

integer

A value between 0 and 59

Get this instance's defined month as a numeric value from 1 to 12

getMonth() : integer

Response

integer

A value between 1 and 12

Returns the month name from a numeric month value

getMonthName(integer $month) : string
static

Arguments

$month

integer

A month number between 1 and 12

Response

string

the month name in english and with capital letters, like: JANUARY, FEBRUARY, ...

Get this instance's defined second as a numeric value from 0 to 59

getSecond() : integer

Response

integer

A value between 0 and 59

Get this instance's defined timezone name

getTimeZoneName() : string

Response

string

The UTC timezone name or empty string if no timezone name could be found

Get this instance's defined timezone offset as a numeric value (in seconds)

getTimeZoneOffset() : integer

Response

integer

The UTC timezone offset in seconds

Get this instance's defined year as a numeric value

getYear() : integer

Response

integer

A 4 digits numeric value

Given two valid dateTime values, this method will check if they represent the same date and time value

isEqual(mixed $dateTime1, mixed $dateTime2) : boolean
static
see \org\turbocommons\src\main\php\model\DateTimeObject::__construct

Arguments

$dateTime1

mixed

A valid ISO 8601 dateTime string or a DateTimeObject instance.

$dateTime2

mixed

A valid ISO 8601 dateTime string or a DateTimeObject instance.

Response

boolean

True if the date and time values on both elements are the same

Check if the provided ISO 8601 dateTime value is identical to the date and time from this instance

isEqualTo(mixed $dateTime) : boolean

Arguments

$dateTime

mixed

A valid ISO 8601 dateTime string or a DateTimeObject instance.

Response

boolean

True if both dateTime values are equivalent to the exact same date and time

DateTimeObject class operates only with ISO 8601 strings, which is the international standard for the representation of dates and times.

isValidDateTime(mixed $dateTime) : true
static

Therefore, this method considers a dateTime string value to be valid only if it is a string that follows that standard or a DateTimeObject instance.

see \org\turbocommons\src\main\php\model\DateTimeObject::__construct

Arguments

$dateTime

mixed

A string containing a valid ISO 8601 date/time value or a valid DateTimeObject instance.

Response

true

if the specified value is ISO 8601 or a DateTimeObject instance, false if value contains invalid information.

substract

substract( $value,  $type = 'minutes') 

Arguments

$value

$type

Convert the current instance date and time values to the local timezone offset.

toLocalTimeZone() : \org\turbocommons\src\main\php\model\DateTimeObject

Output the current dateTime instance data as a custom formatted string.

toString(string $formatString = 'Y-M-DTH:N:S.U+Offset') : string

Arguments

$formatString

string

A string containing the output format like 'd/m/Y' or 'm-d-y' where the following characters will be automatically replaced:

  • Y with a four digit year value
  • y with a one or two digit year value
  • M with a two digit month value
  • m with a one or two digit month value
  • D with a two digit day value
  • d with a one or two digit day value
  • H with a two digit hour value
  • h with a one or two digit hour value
  • N with a two digit minutes value
  • n with a one or two digit minutes value
  • S with a two digit seconds value
  • s with a one or two digit seconds value
  • U with a 6 digit microseconds value
  • u with a 3 digit miliseconds value
  • Offset with the timezone offset value

Response

string

The dateTime with the specified format.

Convert the current instance date and time values to the UTC zero timezone offset.

toUTC() : \org\turbocommons\src\main\php\model\DateTimeObject
example

this instance contains a +02:00 timezone offset, after calling this method the offset will be +00:00

Response

\org\turbocommons\src\main\php\model\DateTimeObject

This object instance