Docs For Class Date

void Date(
[mixed
$date = null], [bool
$pb_countleapseconds = DATE_COUNT_LEAP_SECONDS])

Constructor

Creates a new Date Object initialized to the current date/time in the system-default timezone by default. A date optionally passed in may be in the ISO 8601, TIMESTAMP or UNIXTIME format, or another Date object. If no date is passed, the current date/time is used.

If a date is passed and an exception is returned by 'setDate()' there is nothing that this function can do, so for this reason, it is advisable to pass no parameter and to make a separate call to 'setDate()'. A date/time should only be passed if known to be a valid ISO 8601 string or a valid Unix timestamp.

See: Date::setDate()
Access: public

Parameters:

mixed	`$date`	—	optional ISO 8601 date/time to initialize; or, a Unix time stamp
bool	`$pb_countleapseconds`	—	whether to count leap seconds (defaults to DATE_COUNT_LEAP_SECONDS)

[ Top ]

void addDays(
int
$pn_days)

Converts the date to the specified no of days from the given date

To subtract days use a negative value for the '$pn_days' parameter

Since: Method available since Release 1.5.0
Access: public

Parameters:

int $pn_days — days to add

[ Top ]

void addHours(
int
$pn_hours)

Converts the date to the specified no of hours from the given date

To subtract hours use a negative value for the '$pn_hours' parameter

Since: Method available since Release 1.5.0
Access: public

Parameters:

int $pn_hours — hours to add

[ Top ]

void addMinutes(
int
$pn_minutes)

Converts the date to the specified no of minutes from the given date

To subtract minutes use a negative value for the '$pn_minutes' parameter

Since: Method available since Release 1.5.0
Access: public

Parameters:

int $pn_minutes — minutes to add

[ Top ]

void addMonths(
int
$pn_months)

Converts the date to the specified no of months from the given date

To subtract months use a negative value for the '$pn_months' parameter

Since: Method available since Release 1.5.0
Access: public

Parameters:

int $pn_months — months to add

[ Top ]

void addSeconds(
mixed
$sec, [bool
$pb_countleap = null])

Adds a given number of seconds to the date

Access: public

Parameters:

mixed	`$sec`	—	the no of seconds to add as integer or float
bool	`$pb_countleap`	—	whether to count leap seconds (defaults to value of count-leap-second object property)

[ Top ]

void addSpan(
object
$span)

Adds a time span to the date

A time span is defined as a unsigned no of days, hours, minutes and seconds, where the no of minutes and seconds must be less than 60, and the no of hours must be less than 24.

A span is added (and subtracted) according to the following logic:

Hours, minutes and seconds are added such that if they fall over a leap second, the leap second is ignored, and not counted. For example, if a leap second occurred at 23.59.60, the following calculations:

23.59.59 + one second 23.59.00 + one minute 23.00.00 + one hour

would all produce 00.00.00 the next day.

A day is treated as equivalent to 24 hours, so if the clocks went backwards at 01.00, and one day was added to the time 00.30, the result would be 23.30 the same day.

This is the implementation which is thought to yield the behaviour that the user is most likely to expect, or in another way of looking at it, it is the implementation that produces the least unexpected behaviour. It basically works in hours, that is, a day is treated as exactly equivalent to 24 hours, and minutes and seconds are treated as equivalent to 1/60th and 1/3600th of an hour. It should be obvious that working in days is impractical; working in seconds is problematic when it comes to adding days that fall over leap seconds, where it would appear to most users that the function adds only 23 hours, 59 minutes and 59 seconds. It is also problematic to work in any kind of mixture of days, hours, minutes, and seconds, because then the addition of a span would sometimes depend on which order you add the constituent parts, which undermines the concept of a span altogether.

If you want alternative functionality, you must use a mixture of the following functions instead:

addYears() addMonths() addDays() addHours() addMinutes() addSeconds()

Access: public

Parameters:

object $span — the time span to add

[ Top ]

void addYears(
int
$pn_years)

Converts the date to the specified no of years from the given date

To subtract years use a negative value for the '$pn_years' parameter

Since: Method available since Release 1.5.0
Access: public

Parameters:

int $pn_years — years to add

[ Top ]

boolean after(
object
$when)

Test if this date/time is after a certain date/time

Return: true if this date is after $when
Access: public

Parameters:

object $when — the Date object to test against

[ Top ]

boolean before(
object
$when)

Test if this date/time is before a certain date/time

Return: true if this date is before $when
Access: public

Parameters:

object $when — the Date object to test against

[ Top ]

int compare(
object
$od1, object
$od2)

Compares two dates

Suitable for use in sorting functions.

Return: 0 if the dates are equal, -1 if '$od1' is before '$od2', 1 if '$od1' is after '$od2'
Access: public

Parameters:

object	`$od1`	—	the first Date object to compare
object	`$od2`	—	the second Date object to compare

[ Top ]

void convertTZ(
object
$tz)

Converts this date to a new time zone

Previously this might not have worked correctly if your system did not allow putenv() or if localtime() did not work in your environment, but this implementation is no longer used.

See: Date::convertTZByID()
Access: public

Parameters:

object $tz — Date_TimeZone object to convert to

[ Top ]

void convertTZByID(
string
$ps_id)

Converts this date to a new time zone, given a valid time zone ID

Previously this might not have worked correctly if your system did not allow putenv() or if localtime() does not work in your environment, but this implementation is no longer used.

See: Date::setTZByID(), Date_TimeZone::isValidID(), Date_TimeZone::Date_TimeZone()
Access: public

Parameters:

string $ps_id — a valid time zone id, e.g. 'Europe/London'

[ Top ]

void copy(
object
$date)

Copy values from another Date object

Makes this Date a copy of another Date object. This is a PHP4-compatible implementation of '__clone()' in PHP5.

Access: public

Parameters:

object $date — Date object to copy

[ Top ]

mixed dateDiff(
object
$po_date, [bool
$pb_ignoretime = false])

Subtract supplied date and return answer in days

If the second parameter '$pb_ignoretime' is specified as false, the time parts of the two dates will be ignored, and the integral no of days between the day-month-year parts of the two dates will be returned. If either of the two dates have an invalid time, the integral no of days will also be returned, else the returned value will be the no of days as a float, with each hour being treated as 1/24th of a day and so on.

For example, 21/11/2007 13.00 minus 21/11/2007 01.00 returns 0.5

Note that if the passed date is in the past, a positive value will be returned, and if it is in the future, a negative value will be returned.

Return: days between two dates as int or float
Since: Method available since Release 1.5.0
Access: public

Parameters:

object	`$po_date`	—	date to subtract
bool	`$pb_ignoretime`	—	whether to ignore the time values of the two dates in subtraction (defaults to false)

[ Top ]

boolean equals(
object
$when)

Test if this date/time is exactly equal to a certain date/time

Return: true if this date is exactly equal to $when
Access: public

Parameters:

object $when — the Date object to test against

[ Top ]

string format(
string
$format)

Date pretty printing, similar to strftime()

Formats the date in the given format, much like strftime(). Most strftime() options are supported.

Formatting options:

%a

abbreviated weekday name (Sun, Mon, Tue)

%A

full weekday name (Sunday, Monday, Tuesday)

%b

abbreviated month name (Jan, Feb, Mar)

%B

full month name (January, February, March)

%C

century number (the year divided by 100 and truncated to an integer, range 00 to 99)

%d

day of month (range 00 to 31)

%D

equivalent to "%m/%d/%y"

%e

day of month without leading noughts (range 0 to 31)

%E

Julian day - no of days since Monday, 24th November, 4714 B.C. (in the proleptic Gregorian calendar)

%g

like %G, but without the century

%G

the 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.

%h

hour as decimal number without leading noughts (0 to 23)

%H

hour as decimal number (00 to 23)

%i

hour as decimal number on 12-hour clock without leading noughts (1 to 12)

%I

hour as decimal number on 12-hour clock (01 to 12)

%j

day of year (range 001 to 366)

%m

month as decimal number (range 01 to 12)

%M

minute as a decimal number (00 to 59)

%n

newline character ("\n")

%o

raw timezone offset expressed as '+/-HH:MM'

%O

dst-corrected timezone offset expressed as '+/-HH:MM'

%p

either 'am' or 'pm' depending on the time

%P

either 'AM' or 'PM' depending on the time

%r

time in am/pm notation; equivalent to "%I:%M:%S %p"

%R

time in 24-hour notation; equivalent to "%H:%M"

%s

seconds including the micro-time (the decimal representation less than one second to six decimal places

%S

seconds as a decimal number (00 to 59)

%t

tab character ("\t")

%T

current time; equivalent to "%H:%M:%S"

%u

day of week as decimal (1 to 7; where 1 = Monday)

%U

week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week (i.e. the first full week of the year, and the week that contains 7th January) (00 to 53)

%V

the ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. (Use %G or %g for the year component that corresponds to the week number for the specified timestamp.)

%w

day of week as decimal (0 to 6; where 0 = Sunday)

%W

week number of the current year as a decimal number, starting with the first Monday as the first day of the first week (i.e. the first full week of the year, and the week that contains 7th January) (00 to 53)

%y

year as decimal (range 00 to 99)

%Y

year as decimal including century (range 0000 to 9999)

%Z

Abbreviated form of time zone name, e.g. 'GMT', or the abbreviation for Summer time if the date falls in Summer time, e.g. 'BST'.

%%

literal '%'

The following codes render a different output to that of 'strftime()':

%e

in 'strftime()' a single digit is preceded by a space

%h

in 'strftime()' is equivalent to '%b'

%U

'%U' and '%W' are different in 'strftime()' in that if week 1 does not start on 1st January, '00' is returned, whereas this function returns '53', that is, the week is counted as the last of the previous year.

%W

Return: date/time in given format
Access: public

Parameters:

string $format — the format string for returned date/time

[ Top ]

string format2(
string
$ps_format, [string
$ps_locale = "en_GB"])

Extended version of 'format()' with variable-length formatting codes

Most codes reproduce the no of digits equal to the length of the code, for example, 'YYY' will return the last 3 digits of the year, and so the year 2007 will produce '007', and the year 89 will produce '089', unless the no-padding code is used as in 'NPYYY', which will return '89'.

For negative values, the sign will be discarded, unless the 'S' code is used in combination, but note that for positive values the value will be padded with a leading space unless it is suppressed with the no-padding modifier, for example for 2007:

YYYY

returns '2007'

SYYYY

returns ' 2007'

NPSYYYY

returns '2007'

The no-padding modifier 'NP' can be used with numeric codes to suppress leading (or trailing in the case of code 'F') noughts, and with character-returning codes such as 'DAY' to suppress trailing spaces, which will otherwise be padded to the maximum possible length of the return-value of the code; for example, for Monday:

Day

returns 'Monday ' because the maximum length of this code is 'Wednesday';

NPDay

returns 'Monday'

N.B. this code affects the code immediately following only, and without this code the default is always to apply padding.

Most character-returning codes, such as 'MONTH', will set the capitalization according to the code, so for example:

MONTH

returns upper-case spelling, e.g. 'JANUARY'

Month

returns spelling with first character of each word capitalized, e.g. 'January'

month

returns lower-case spelling, e.g. 'january'

Where it makes sense, numeric codes can be combined with a following 'SP' code which spells out the number, or with a 'TH' code, which renders the code as an ordinal ('TH' only works in English), for example, for 31st December:

DD

returns '31'

DDTH

returns '31ST'

DDth

returns '31st'

DDSP

returns 'THIRTY-ONE'

DDSp

returns 'Thirty-one'

DDsp

returns 'thirty-one'

DDSPTH

returns 'THIRTY-FIRST'

DDSpth

returns 'Thirty-first'

DDspth

returns 'thirty-first'

All formatting options:

All punctuation and white-space is reproduced unchanged

"text"

Quoted text is reproduced unchanged (escape using '\')

AD

AD indicator with or without full stops; N.B. if you are using 'Astronomical' year numbering then 'A.D./B.C.' indicators will be out for negative years

A.D.

AM

Meridian indicator with or without full stops

A.M.

BC

BC indicator with or without full stops

B.C.

BCE

BCE indicator with or without full stops

B.C.E.

CC

Century, i.e. the year divided by 100, discarding the remainder; 'S' prefixes negative years with a minus sign

SCC

CE

CE indicator with or without full stops

C.E.

Day of week (0-6), where 0 represents Sunday

DAY

Name of day, padded with blanks to display width of the widest name of day in the locale of the machine

DD

Day of month (1-31)

DDD

Day of year (1-366)

DY

Abbreviated name of day

FFF

Fractional seconds; no radix character is printed. The no of 'F's determines the no of digits of the part-second to return; e.g. 'HH:MI:SS.FF'

F[integer]

The integer after 'F' specifies the number of digits of the part-second to return. This is an alternative to using F[integer], and 'F3' is thus equivalent to using 'FFF'.

HH

Hour of day (0-23)

HH12

Hour of day (1-12)

HH24

Hour of day (0-23)

ID

Day of week (1-7) based on the ISO standard

IW

Week of year (1-52 or 1-53) based on the ISO standard

IYYY

4-digit year based on the ISO 8601 standard; 'S' prefixes negative years with a minus sign

SIYYY

IYY

Last 3, 2, or 1 digit(s) of ISO year

IY

Julian day - the number of days since Monday, 24th November, 4714 B.C. (proleptic Gregorian calendar)

MI

Minute (0-59)

MM

Month (01-12; January = 01)

MON

Abbreviated name of month

MONTH

Name of month, padded with blanks to display width of the widest name of month in the date language used for

PM

Meridian indicator with or without full stops

P.M.

Quarter of year (1, 2, 3, 4; January - March = 1)

RM

Roman numeral month (I-XII; January = I); N.B. padded with leading spaces.

SS

Second (0-59)

SSSSS

Seconds past midnight (0-86399)

TZC

Abbreviated form of time zone name, e.g. 'GMT', or the abbreviation for Summer time if the date falls in Summer time, e.g. 'BST'. N.B. this is not a unique identifier - for this purpose use the time zone region (code 'TZR').

TZH

Time zone hour; 'S' prefixes the hour with the correct sign, (+/-), which otherwise is not displayed. Note that the leading nought can be suppressed with the no-padding code 'NP'). Also note that if you combine with the 'SP' code, the sign will not be spelled out. (I.e. 'STZHSp' will produce '+One', for example, and not 'Plus One'. 'TZH:TZM' will produce, for example, '+05:30'. (Also see 'TZM' format code)

STZH

TZI

Whether or not the date is in Summer time (daylight saving time). Returns '1' if Summer time, else '0'.

TZM

Time zone minute, without any +/- sign. (Also see 'TZH' format element)

TZN

Long form of time zone name, e.g. 'Greenwich Mean Time', or the name of the Summer time if the date falls in Summer time, e.g. 'British Summer Time'. N.B. this is not a unique identifier - for this purpose use the time zone region (code 'TZR').

TZO

Time zone offset in ISO 8601 form - that is, 'Z' if UTC, else [+/-][hh]:[mm] (which would be equivalent to 'STZH:TZM'). Note that this result is right padded with spaces by default, (i.e. if 'Z').

TZS

Time zone offset in seconds; 'S' prefixes negative sign with minus sign '-' if negative, and no sign if positive (i.e. -43200 to 50400).

STZS

TZR

Time zone region, that is, the name or ID of the time zone e.g. 'Europe/London'. This value is unique for each time zone.

Seconds since the Unix Epoch - January 1 1970 00:00:00 GMT

'Absolute' week of month (1-5), counting week 1 as 1st-7th of the year, regardless of the day

W1

Week of year (1-54), counting week 1 as the week that contains 1st January

W4

Week of year (1-53), counting week 1 as the week that contains 4th January (i.e. first week with at least 4 days)

W7

Week of year (1-53), counting week 1 as the week that contains 7th January (i.e. first full week)

WW

'Absolute' week of year (1-53), counting week 1 as 1st-7th of the year, regardless of the day

YEAR

Year, spelled out; 'S' prefixes negative years with 'MINUS'; N.B. 'YEAR' differs from 'YYYYSP' in that the first will render 1923, for example, as 'NINETEEN TWENTY-THREE, and the second as 'ONE THOUSAND NINE HUNDRED TWENTY-THREE'

SYEAR

YYYY

4-digit year; 'S' prefixes negative years with a minus sign

SYYYY

YYY

Last 3, 2, or 1 digit(s) of year

YY

Y,YYY

Year with thousands-separator in this position; five possible separators

Y.YYY

Y�YYY

N.B. space-dot (mid-dot, interpunct) is valid only in ISO 8859-1 (so take care when using UTF-8 in particular)

YYYY

Y YYY

In addition the following codes can be used in combination with other codes; Codes that modify the next code in the format string:

NP

'No Padding' - Returns a value with no trailing blanks and no leading or trailing noughts; N.B. that the default is to include this padding in the return string. N.B. affects the code immediately following only.

Codes that modify the previous code in the format string (can only be used with integral codes such as 'MM'):

TH

Ordinal number

SP

Spelled cardinal number

SPTH

Spelled ordinal number (combination of 'SP' and 'TH' in any order)

THSP

Code 'SP' can have the following three variations (which can also be used in combination with 'TH'):

SP

returns upper-case spelling, e.g. 'FOUR HUNDRED'

Sp

returns spelling with first character of each word capitalized, e.g. 'Four Hundred'

sp

returns lower-case spelling, e.g. 'four hundred'

Code 'TH' can have the following two variations (although in combination with code 'SP', the case specification of 'SP' takes precedence):

TH

returns upper-case ordinal suffix, e.g. 400TH

th

returns lower-case ordinal suffix, e.g. 400th

Return: date/time in given format
Since: Method available since Release 1.5.0
Access: public

Parameters:

string	`$ps_format`	—	format string for returned date/time
string	`$ps_locale`	—	language name abbreviation used for formatting numbers as spelled-out words

[ Top ]

string format3(
string
$ps_format)

Formats the date in the same way as 'format()', but using the formatting codes used by the PHP function 'date()'

All 'date()' formatting options are supported except 'B'. This function also responds to the DATE_* constants, such as DATE_COOKIE, which are specified at:

http://www.php.net/manual/en/ref.datetime.php#datetime.constants

Formatting options:

(Day)

Day of the month, 2 digits with leading zeros (01 to 31)

A textual representation of a day, three letters ('Mon' to 'Sun')

Day of the month without leading zeros (1 to 31)

[lowercase 'L'] A full textual representation of the day of the week ('Sunday' to 'Saturday')

ISO-8601 numeric representation of the day of the week (1 (for Monday) to 7 (for Sunday))

English ordinal suffix for the day of the month, 2 characters ('st', 'nd', 'rd' or 'th')

Numeric representation of the day of the week (0 (for Sunday) to 6 (for Saturday))

The day of the year, starting from 0 (0 to 365)

(Week)

ISO-8601 week number of year, weeks starting on Monday (00 to 53)

(Month)

A full textual representation of a month ('January' to 'December')

Numeric representation of a month, with leading zeros (01 to 12)

A short textual representation of a month, three letters ('Jan' to 'Dec')

Numeric representation of a month, without leading zeros (1 to 12)

Number of days in the given month (28 to 31)

(Year)

Whether it is a leap year (1 if it is a leap year, 0 otherwise)

ISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.

A full numeric representation of a year, 4 digits (0000 to 9999)

A two digit representation of a year (00 to 99)

(Time)

Lowercase Ante meridiem and Post meridiem ('am' or 'pm')

Uppercase Ante meridiem and Post meridiem ('AM' or 'PM')

12-hour format of an hour without leading zeros (1 to 12)

24-hour format of an hour without leading zeros (0 to 23)

12-hour format of an hour with leading zeros (01 to 12)

24-hour format of an hour with leading zeros (00 to 23)

Minutes with leading zeros (00 to 59)

Seconds, with leading zeros (00 to 59)

Milliseconds, e.g. '54321'

(Time Zone)

Timezone identifier, e.g. Europe/London

Whether or not the date is in Summer time (1 if Summer time, 0 otherwise)

Difference to Greenwich time (GMT) in hours, e.g. '+0200'

Difference to Greenwich time (GMT) with colon between hours and minutes, e.g. '+02:00'

Timezone abbreviation, e.g. 'GMT', 'EST'

Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. (-43200 to 50400)

(Full Date/Time)

ISO 8601 date, e.g. '2004-02-12T15:19:21+00:00'

RFC 2822 formatted date, e.g. 'Thu, 21 Dec 2000 16:01:07 +0200'

Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)

Return: date/time in given format
Since: Method available since Release 1.5.0
Access: public

Parameters:

string $ps_format — the format string for returned date/time

[ Top ]

string getDate(
[int
$format = DATE_FORMAT_ISO])

Gets a string (or other) representation of this date

Returns a date in the format specified by the DATE_FORMAT_* constants.

Return: the date in the requested format
Access: public

Parameters:

int $format — format constant (DATE_FORMAT_*) of the output date

[ Top ]

int getDay(
)

Returns the day field of the date object

Return: the day
Access: public

[ Top ]

string getDayName(
[bool
$abbr = false], [int
$length = 3])

Gets the full name or abbreviated name of this weekday

Return: name of this day
Access: public

Parameters:

bool	`$abbr`	—	abbreviate the name
int	`$length`	—	length of abbreviation

[ Top ]

int getDayOfWeek(
)

Gets the day of the week for this date (0 = Sunday)

Return: the day of the week (0 = Sunday)
Access: public

[ Top ]

int getDayOfYear(
)

Returns the no of days (1-366) since 31st December of the previous year

Return: an integer between 1 and 366
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getDaysInMonth(
)

Gets number of days in the month for this date

Return: number of days in this month
Access: public

[ Top ]

int getHour(
)

Returns the hour field of the date object

Return: the hour
Access: public

[ Top ]

int getJulianDate(
)

Returns the no of days (1-366) since 31st December of the previous year

N.B. this function does not return (and never has returned) the 'Julian Date', as described, for example, at:

http://en.wikipedia.org/wiki/Julian_day

If you want the day of the year (0-366), use 'getDayOfYear()' instead. If you want the true Julian Day, call one of the following:

format("%E")

format2("J")

There currently is no function that calls the Julian Date (as opposed to the 'Julian Day'), although the Julian Day is an approximation.

Return: the Julian date
See: Date::getDayOfYear()
Deprecated: Method deprecated in Release 1.5.0
Access: public

[ Top ]

int getMinute(
)

Returns the minute field of the date object

Return: the minute
Access: public

[ Top ]

int getMonth(
)

Returns the month field of the date object

Return: the minute
Access: public

[ Top ]

string getMonthName(
[boolean
$abbr = false])

Gets the full name or abbreviated name of this month

Return: name of this month
Access: public

Parameters:

boolean $abbr — abbreviate the name

[ Top ]

object Date getNextDay(
)

Get a Date object for the day after this one

The time of the returned Date object is the same as this time.

Return: object representing the next day
Access: public

[ Top ]

object Date getNextWeekday(
)

Get a Date object for the weekday after this one

The time of the returned Date object is the same as this time.

Return: object representing the next week-day
Access: public

[ Top ]

float getPartSecond(
)

Returns the part-second field of the date object

Return: the part-second
Since: Method available since Release 1.5.0
Access: protected

[ Top ]

object Date getPrevDay(
)

Get a Date object for the day before this one

The time of the returned Date object is the same as this time.

Return: object representing the previous day
Access: public

[ Top ]

object Date getPrevWeekday(
)

Get a Date object for the weekday before this one

The time of the returned Date object is the same as this time.

Return: object representing the previous week-day
Access: public

[ Top ]

int getQuarterOfYear(
)

Gets the quarter of the year for this date

Return: the quarter of the year (1-4)
Access: public

[ Top ]

int getSecond(
)

Returns the second field of the date object

Return: the second
Access: public

[ Top ]

float getSecondsPastMidnight(
)

Returns the no of seconds since midnight (0-86400) as float

Return: float which is at least 0 and less than 86400
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getStandardDay(
)

Returns the day field of the local standard time

Return: the day
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getStandardHour(
)

Returns the hour field of the local standard time

Return: the hour
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getStandardMinute(
)

Returns the minute field of the local standard time

Return: the minute
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getStandardMonth(
)

Returns the month field of the local standard time

Return: the minute
Since: Method available since Release 1.5.0
Access: public

[ Top ]

float getStandardPartSecond(
)

Returns the part-second field of the local standard time

Return: the part-second
Since: Method available since Release 1.5.0
Access: protected

[ Top ]

int getStandardSecond(
)

Returns the second field of the local standard time

Return: the second
Since: Method available since Release 1.5.0
Access: public

[ Top ]

float getStandardSecondsPastMidnight(
)

Returns the no of seconds since midnight (0-86400) of the local standard time as float

Return: float which is at least 0 and less than 86400
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getStandardYear(
)

Returns the year field of the local standard time

Return: the year
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getTime(
)

Returns the date/time in Unix time() format

Returns a representation of this date in Unix time() format. This may only be valid for dates from 1970 to ~2038.

Return: number of seconds since the unix epoch
Access: public

[ Top ]

string getTZID(
)

Returns the unique ID of the time zone, e.g. 'America/Chicago'

Return: the time zone ID
Since: Method available since Release 1.5.0
Access: public

[ Top ]

string getTZLongName(
)

Returns the long name of the time zone

Returns long form of time zone name, e.g. 'Greenwich Mean Time'. N.B. if the date falls in Summer time, the Summer time name will be returned instead, e.g. 'British Summer Time'.

N.B. this is not a unique identifier for the time zone - for this purpose use the time zone ID.

Return: the long name of the time zone
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getTZOffset(
)

Returns the DST-corrected offset from UTC for the given date

Gets the offset to UTC for a given date/time, taking into account daylight savings time, if the time zone observes it and if it is in effect.

N.B. that the offset is calculated historically and in the future according to the current Summer time rules, and so this function is proleptically correct, but not necessarily historically correct. (Although if you want to be correct about times in the distant past, this class is probably not for you because the whole notion of time zones does not apply, and historically there are so many time zone changes, Summer time rule changes, name changes, calendar changes, that calculating this sort of information is beyond the scope of this package altogether.)

Return: the corrected offset to UTC in milliseconds
Since: Method available since Release 1.5.0
Access: public

[ Top ]

string getTZShortName(
)

Returns the short name of the time zone

Returns abbreviated form of time zone name, e.g. 'GMT'. N.B. if the date falls in Summer time, the Summer time name will be returned instead, e.g. 'BST'.

N.B. this is not a unique identifier - for this purpose use the time zone ID.

Return: the short name of the time zone
Since: Method available since Release 1.5.0
Access: public

[ Top ]

int getWeekOfYear(
)

Gets the week of the year for this date

Return: the week of the year
Access: public

[ Top ]

int getWeeksInMonth(
)

Gets the number of weeks in the month for this date

Return: number of weeks in this month
Access: public

[ Top ]

int getYear(
)

Returns the year field of the date object

Return: the year
Access: public

[ Top ]

boolean inDaylightTime(
[bool
$pb_repeatedhourdefault = false])

Tests if this date/time is in DST

Returns true if daylight savings time is in effect for this date in this date's time zone.

Return: true if DST is in effect for this date
Access: public

Parameters:

bool $pb_repeatedhourdefault — value to return if repeated hour is specified (defaults to false)

[ Top ]

bool inEquivalentTimeZones(
object
$po_date1, object
$po_date2)

Tests whether two dates are in equivalent time zones

Equivalence in this context consists in the time zones of the two dates having:

an equal offset from UTC in both standard and Summer time (if the time zones observe Summer time) the same Summer time start and end rules, that is, the two time zones must switch from standard time to Summer time, and vice versa, on the same day and at the same time

An example of two equivalent time zones is 'Europe/London' and 'Europe/Lisbon', which in London is known as GMT/BST, and in Lisbon as WET/WEST.

Return: true if the time zones are equivalent
Since: Method available since Release 1.5.0
Access: public

Parameters:

object	`$po_date1`	—	the first Date object to compare
object	`$po_date2`	—	the second Date object to compare

[ Top ]

boolean isFuture(
)

Determine if this date is in the future

Return: true if this date is in the future
Access: public

[ Top ]

boolean isLeapYear(
)

Determine if the year in this date is a leap year

Return: true if this year is a leap year
Access: public

[ Top ]

boolean isPast(
)

Determine if this date is in the past

Return: true if this date is in the past
Access: public

[ Top ]

bool isTimeValid(
)

Whether the stored time is valid as a local time

An invalid time is one that lies in the 'skipped hour' at the point that the clocks go forward. Note that the stored date (i.e. the day/month/year, is always valid).

The object is able to store an invalid time because a user might unwittingly and correctly store a valid time, and then add one day so as to put the object in the 'skipped' hour (when the clocks go forward). This could be corrected by a conversion to Summer time (by adding one hour); however, if the user then added another day, and had no need for or interest in the time anyway, the behaviour may be rather unexpected. And anyway in this situation, the time originally specified would now, two days on, be valid again.

So this class allows an invalid time like this so long as the user does not in any way make use of or request the time while it is in this semi-invalid state, in order to allow for for the fact that he might be only interested in the date, and not the time, and in order not to behave in an unexpected way, especially without throwing an exception to tell the user about it.

Since: Method available since Release 1.5.0
Access: public

[ Top ]

void round(
[int
$pn_precision = DATE_PRECISION_DAY], [bool
$pb_correctinvalidtime = DATE_CORRECTINVALIDTIME_DEFAULT])

Rounds the date according to the specified precision (defaults to nearest day)

The precision parameter must be one of the following constants:

DATE_PRECISION_YEAR

DATE_PRECISION_MONTH

DATE_PRECISION_DAY

DATE_PRECISION_HOUR

DATE_PRECISION_10MINUTES

DATE_PRECISION_MINUTE

DATE_PRECISION_10SECONDS

DATE_PRECISION_SECOND

N.B. the default is DATE_PRECISION_DAY

The precision can also be specified as an integral offset from one of these constants, where the offset reflects a precision of 10 to the power of the offset greater than the constant. For example:

DATE_PRECISION_YEAR - 1

rounds the date to the nearest 10 years

DATE_PRECISION_YEAR - 3

rounds the date to the nearest 1000 years

DATE_PRECISION_SECOND + 1

rounds the date to 1 decimal point of a second

DATE_PRECISION_SECOND + 3

rounds the date to 3 decimal points of a second

DATE_PRECISION_SECOND - 1

rounds the date to the nearest 10 seconds (thus it is equivalent to DATE_PRECISION_10SECONDS)

Since: Method available since Release 1.5.0
Access: public

Parameters:

int	`$pn_precision`	—	a 'DATE_PRECISION_*' constant
bool	`$pb_correctinvalidtime`	—	whether to correct, by adding the local Summer time offset, the rounded time if it falls in the skipped hour (defaults to DATE_CORRECTINVALIDTIME_DEFAULT)

[ Top ]

void roundSeconds(
[int
$pn_precision = 0], [bool
$pb_correctinvalidtime = DATE_CORRECTINVALIDTIME_DEFAULT])

Rounds seconds up or down to the nearest specified unit

N.B. this function is equivalent to calling:

'round(DATE_PRECISION_SECOND + $pn_precision)'

Since: Method available since Release 1.5.0
Access: public

Parameters:

int	`$pn_precision`	—	number of digits after the decimal point
bool	`$pb_correctinvalidtime`	—	whether to correct, by adding the local Summer time offset, the rounded time if it falls in the skipped hour (defaults to DATE_CORRECTINVALIDTIME_DEFAULT)

[ Top ]

void setDate(
string
$date, [int
$format = DATE_FORMAT_ISO], [bool
$pb_repeatedhourdefault = false])

Sets the fields of a Date object based on the input date and format

Format parameter should be one of the specified DATE_FORMAT_* constants:

DATE_FORMAT_ISO

'YYYY-MM-DD HH:MI:SS' DATE_FORMAT_ISO_BASIC
'YYYYMMSSTHHMMSS(Z|(+/-)HHMM)?' DATE_FORMAT_ISO_EXTENDED
'YYYY-MM-SSTHH:MM:SS(Z|(+/-)HH:MM)?' DATE_FORMAT_ISO_EXTENDED_MICROTIME
'YYYY-MM-SSTHH:MM:SS(.S*)?(Z|(+/-)HH:MM)?' DATE_FORMAT_TIMESTAMP
'YYYYMMDDHHMMSS' DATE_FORMAT_UNIXTIME
long integer of the no of seconds since the Unix Epoch (1st January 1970 00.00.00 GMT)

Access: public

Parameters:

string	`$date`	—	input date
int	`$format`	—	optional format constant (DATE_FORMAT_*) of the input date. This parameter is not needed, except to force the setting of the date from a Unix time-stamp (DATE_FORMAT_UNIXTIME).
bool	`$pb_repeatedhourdefault`	—	value to return if repeated hour is specified (defaults to false)

[ Top ]

void setDateTime(
int
$pn_day, int
$pn_month, int
$pn_year, int
$pn_hour, int
$pn_minute, mixed
$pm_second, [bool
$pb_repeatedhourdefault = false])

Sets all the fields of the date object (day, month, year, hour, minute and second)

If specified year forms an invalid date, then PEAR error will be returned. Note that setting each of these fields separately may unintentionally return a PEAR error if a transitory date is invalid between setting these fields.

N.B. if the repeated hour, due to the clocks going back, is specified, the default is to assume local standard time.

See: Date::setDayMonthYear(), Date::setHourMinuteSecond()
Since: Method available since Release 1.5.0
Access: public

Parameters:

int	`$pn_day`	—	the day
int	`$pn_month`	—	the month
int	`$pn_year`	—	the year
int	`$pn_hour`	—	the hour
int	`$pn_minute`	—	the minute
mixed	`$pm_second`	—	the second as integer or float
bool	`$pb_repeatedhourdefault`	—	whether to assume Summer time if a repeated hour is specified (defaults to false)

[ Top ]

void setDay(
int
$d, [bool
$pb_validate = DATE_VALIDATE_DATE_BY_DEFAULT])

Sets the day field of the date object

If specified year forms an invalid date, then PEAR error will be returned, unless the validation is over-ridden using the second parameter.

See: Date::setDayMonthYear(), Date::setDateTime()
Access: public

Parameters:

int	`$d`	—	the day
bool	`$pb_validate`	—	whether to check that the new date is valid

[ Top ]

void setDayMonthYear(
int
$d, int
$m, int
$y)

Sets the day, month and year fields of the date object

If specified year forms an invalid date, then PEAR error will be returned. Note that setting each of these fields separately may unintentionally return a PEAR error if a transitory date is invalid between setting these fields.

See: Date::setDateTime()
Since: Method available since Release 1.5.0
Access: public

Parameters:

int	`$d`	—	the day
int	`$m`	—	the month
int	`$y`	—	the year

[ Top ]

void setHour(
int
$h, [bool
$pb_repeatedhourdefault = false])

Sets the hour field of the date object

Expects an hour in 24-hour format.

See: Date::setHourMinuteSecond(), Date::setDateTime()
Access: public

Parameters:

int	`$h`	—	the hour
bool	`$pb_repeatedhourdefault`	—	whether to assume Summer time if a repeated hour is specified (defaults to false)

[ Top ]

void setHourMinuteSecond(
int
$h, int
$m, mixed
$s, [bool
$pb_repeatedhourdefault = false])

Sets the hour, minute, second and part-second fields of the date object

N.B. if the repeated hour, due to the clocks going back, is specified, the default is to assume local standard time.

See: Date::setDateTime()
Since: Method available since Release 1.5.0
Access: public

Parameters:

int	`$h`	—	the hour
int	`$m`	—	the minute
mixed	`$s`	—	the second as integer or float
bool	`$pb_repeatedhourdefault`	—	whether to assume Summer time if a repeated hour is specified (defaults to false)

[ Top ]

void setLocalTime(
int
$pn_day, int
$pn_month, int
$pn_year, int
$pn_hour, int
$pn_minute, int
$pn_second, float
$pn_partsecond, [bool
$pb_repeatedhourdefault = false], [bool
$pb_correctinvalidtime = DATE_CORRECTINVALIDTIME_DEFAULT])

Class: Date

Class Overview

Author(s):

Version:

Copyright:

Methods

Inherited Variables

Inherited Methods

Class Details

Method Detail

Date (Constructor) [line 455]

Parameters:

addDays [line 3750]

Parameters:

addHours [line 3782]

Parameters:

addMinutes [line 3821]

Parameters:

addMonths [line 3718]

Parameters:

addSeconds [line 3861]

Parameters:

addSpan [line 4052]

Parameters:

addYears [line 3685]

Parameters:

after [line 4366]

Parameters:

before [line 4341]

Parameters:

compare [line 4278]

Parameters:

convertTZ [line 3541]

Parameters:

convertTZByID [line 3616]

Parameters:

copy [line 489]

Parameters:

dateDiff [line 4189]

Parameters:

equals [line 4391]

Parameters:

format [line 1220]

Parameters:

format2 [line 1953]

Parameters:

format3 [line 3077]

Parameters:

getDate [line 1075]

Parameters:

getDay [line 4747]

getDayName [line 4586]

Parameters:

getDayOfWeek [line 4508]

getDayOfYear [line 4493]

getDaysInMonth [line 4553]

getHour [line 4868]

getJulianDate [line 4477]

getMinute [line 4886]

getMonth [line 4732]

getMonthName [line 4612]

Parameters:

getNextDay [line 4633]

getNextWeekday [line 4671]

getPartSecond [line 4945]

getPrevDay [line 4652]

getPrevWeekday [line 4695]

getQuarterOfYear [line 4538]

getSecond [line 4904]

getSecondsPastMidnight [line 4923]

getStandardDay [line 5002]

getStandardHour [line 5021]

getStandardMinute [line 5040]

getStandardMonth [line 4983]

getStandardPartSecond [line 5101]

getStandardSecond [line 5059]

getStandardSecondsPastMidnight [line 5079]

getStandardYear [line 4964]

getTime [line 3226]

getTZID [line 3242]