6.4. Zend_Date API Overview

While the Zend_Date API remains simplistic and unitary, its design remains flexible and powerful through the rich permutations of operations and operands.

6.4.1. Working with Date Values

Once input has been normalized via the creation of a Zend_Date object, it will have an associated timezone. All manipulations of the object are assumed to be relative to this timezone. Beware of mixing and matching operations with date parts between date objects for different timezones, which generally produces undesireable results, unless the manipulations are only related to the timestamp.

The general functions expect a constant providing the date's desired $part, such as Zend_Date::HOUR. These constants are valid for all of the functions below. A list of all available constants is provided in Paragraaf 6.7.2, “List of All Constants” . If no $part is specified, then Zend_Date::TIMESTAMP is assumed.

If there is a $date input parameter, then the $locale parameter disambiguates the $date by explicitly specifying the locale it belongs to (e.g. what language should be used to parse month names). If there is no $date input parameter, then the $locale parameter specifies the locale to use for localizing output (e.g. the date format for a string representation). If no $locale was specified, then the locale of the current object is used to interpret $date.

In the table below, nearly all combinations of "Date Parts" and "Basic Method Types" exist (e.g. addYear()), as well as "Special Types of Date 'Parts'" and the "Basic Method Types" (e.g. subWeek()).

Tabel 6.1. Basic Zend_Date Methods and Part Specific Methods

Basic Method Types Date Parts Special Types of Date "Parts"
add*() Year Timestamp
sub*() Month Date
compare*() Day Week
get*() Hour Weekday
set*() Minute DayOfYear
  Second Arpa
  Millisecond Iso

Each of the basic methods has the same equivalent functionality for each of the data parts supported, as explained below.

  • get($part = null, $locale = null)

    returns the $part of object's date localized to $locale as a formatted string or integer

  • set($date, $part = null, $locale = null)

    sets the $part of the current object to the corresponding value for that part found in the input $date having a locale $locale

  • add($date, $part = null, $locale = null)

    adds the $part of $date having a locale $locale to t the current object's date

  • sub($date, $part = null, $locale = null)

    subtracts the $part of $date having a locale $locale to t the current object's date

  • copyPart($part, $locale = null)

    returns a cloned object, with only $part of the object's date copied to the clone, with the clone have its locale arbitrarily set to $locale (if specified)

  • compare($date, $part = null, $locale = null)

    compares $part of $date to this object's timestamp, returning 0 if they are equal, 1 if this object's part was more recent than $date's part, otherwise -1.

  • equals($date, $part = null, $locale = null)

    returns true, if $part of $date having locale $locale is the same as this object's date $part, otherwise false

  • isEarlier($date, $part = null, $locale = null)

    returns true, if $part of this object's date is earlier than $part of $date having a locale $locale

  • isLater($date, $part = null, $locale = null)

    returns true, if $part of this object's date is later than $part of $date having a locale $locale

6.4.2. Date Part Specific Methods

These convenience methods help us lazy programmers avoid having to type out the date part constants when using the general methods above. The following date-part-specific methods are available:

Tabel 6.2. Detailed functions

Related Output Seting Addition Subtraction Comparation
Unix Timestamp getTimestamp() setTimestamp() addTimestamp() subTimestamp() compareTimestamp()
Date getDate() setDate() addDate() subDate() compareDate()
Time getTime() setTime() addTime() subTime() compareTime()
Year getYear() setYear() addYear() subYear() compareYear()
Month getMonth() setMonth() addMonth() subMonth() compareMonth()
Day getDay() setDay() addDay() subDay() compareDay()
Weekday getWeekday() setWeekday() addWeekday() subWeekday() compareWeekday()
Day of Year getDayOfYear() setDayOfYear() addDayOfYear() subDayOfYear() compareDayOfYear()
Hour getHour() setHour() addHour() subHour() compareHour()
Minute getMinute() setMinute() addMinute() subMinute() compareMinute()
Second getSecond() setSecond() addSecond() subSecond() compareSecond()
Millisecond getMilliSecond() setMilliSecond() addMilliSecond() subMilliSecond() compareMilliSecond()
Week getWeek() setWeek() addWeek() subWeek() compareWeek()
ISO 8601 date getIso() setIso() addIso() subIso() compareIso()
Arpa date getArpa() setArpa() addArpa() subArpa() compareArpa()
TimeZone getTimeZone() setTimeZone()      

6.4.3. Additional Functions

Certainly there are some additional functions not fitting into the above scheme while being helpful.

The following additional functions are available:

Tabel 6.3. Additional Functions

Function Description
toString() Is able to return a user-defined string
toValue() Converts a date to a digit
now() Returns the current date
isLeapYear() Is the year a leap year?
isToday() Is the date today?
isTomorrow() Is the date tomorrow?
isYesterday() is the date yesterday?
getSunRise() Return the date's time of sunrise
getSunSet() Return the date's time of sunset
getSunInfo() Return an array with the date's sun dates
getFractionalPrecision() Return the precision of the part seconds
setFractionalPrecision() Set the precision of the part seconds