The WebAbility® Network Developers - Documentation
WebAbility Site
\dominion\DB_Date Reference

I. Structure:


- Direct Superclass:
WAClass

- Direct known subclasses:
none

II. Description:


2.1. About measuring the time:


This class allow to manipulate the dates and time with a single universal object, without dealing with incoherencies between functions and attributes of dates. The format of the date is unique for its internal representation and operations. Printing the date can be formated at will.

The object is compatible with Unix Timestamp, universal ISO 8901 and RFC-3339: "Date and Time on the Internet: Timestamps".

¿Why a single format? The problem with dates, is nobody can agree on a standard format in any part in the world, nor between brands and products and sometimes not even in a unique product (just start to use the quantity of incompatible dates and time objects into the Informix database for instance to measure the problem of it).

Instead of creating a lots of strange and weird time objects, we preferred to fix us on a unique and standard object to make incredibly easier the programmer's life. The selected format is supposed to be the most used on Internet, backed up with a RFC and ISO standards.

If you need to work with dates and formats from any other non-standard sources, there are enough PHP functions to make the compatible transfer with our object.

Basing the whole programmation on this object you will have no compatibility problem at all with your code nor with the databases.


2.2. Formats:


The universal format of a date/time on Internet is "YYYY-MM-DDTHH24:MI:SS.CCZ":
YYYY is the 4 digits year, interval 0000-9999
MM is the 2 digits month, interval 01-12
DD is the 2 digits day, interval 01-28, 01-29, 01-30 or 01-31 depending on the month and year
T is the letter T or t
HH24 is the 24 hours format hour, interval 00-23
MI are the minutes, interval 00-59
SS are the seconds, interval 00-59
CC are the cents of secongs, interval 00-99
Z is the time zone, it can be Z letter (UTC/GMT), or +/-00 to +/-12

.CC is optional
Z is optional
T* is optional

With the object DB_Date, you can work with dates, time, or timestamp (date and time).

When you create a date, you can pass to the constructor a string that contains a date, a time or a timestamp. Any of the following formats are recognized:
YYYY-MM-DD
HH24:MI:SS
HH24:MI:SS.C
YYYY-MM-DDTHH24:MI:SS
YYYY-MM-DDTHH24:MI:SS.C
YYYY-MM-DDTHH24:MI:SSZ
YYYY-MM-DDTHH24:MI:SS.CZ

It is important to note that separators '-' and ':' can be any character between 'space', '-', ':', '/',
and T can also be a space for easy writing.

The constructor of the date also recognize:
letter N to take the creation time (N as Now).
Unix timestamp Integer.

Examples:

$D = new DB_Date(); // Not initialized
$D = new DB_Date('N'); // Initialized as 'Now'
$D = new DB_Date(time()); // Initialize as 'Now'
$D = new DB_Date('2008-01-01'); // Initialized as a date, default server timezone, and 00:00:00.00 as time
$D = new DB_Date('2008-01-01T12:23:11.56-06'); // Initialized as Mexican time zone (GMT-6)
$T = new DB_Date('15:04:00.50'); // Initialized without date
$T2 = new DB_Date($T); // Initialized with $T date content


2.3. Time zones:


The default time zone can be changed with the static method setDefaultZone($offset)

If it is important for your code to work with correct timezones, you must fix your default time zone at the begining of your code.
You can get the server default time zone with the PHP function date("O", 0); or date("Z", 0); for instance.

2.4. Using the class:


You can directly print the date:
print $D;
This will print the date with the universal format by default YYYY-MM-DDTHH24:MI:SS.CZ if your date is a timestamp, or with a simple date YYYY-MM-DD or a simple hour HH24:MI:SS

You can change the default format with the static method setDefaultFormat($format, $dateformat, $timeformat)

You may also chain the set functions for code compression:


$D = new DB_Date();
$D->setYear(2012)->setMonth(11)->setDay(11);


2.5. Error messages:


If you want to translate the libraries you should consider into the WAMessage XML translation file the following entries:
- DB_Date.badinit: The initialization date is not recognized.
- DB_Date.badzone: The zone is out of authorized bounds -12 to 12:
- DB_Date.baddateobject: The date is not a DB_Date object.
- DB_Date.baddateunix: The date cannot be converted to Unix Time.
- DB_Date.badyear: The year is out of authorized bounds: 1-9999:
- DB_Date.badmonth: The month is out of authorized bounds 1-12:
- DB_Date.daywithoutmonth: The day cannot be set without setting month and year before.
- DB_Date.badday: The day is out of authorized bounds 1-28/31:
- DB_Date.badhour: The hour is out of authorized bounds 0-23:
- DB_Date.badminutes: The minutes are out of authorized bounds 0-59:
- DB_Date.badseconds: The seconds are out of authorized bounds 0-59:
- DB_Date.badcents: The cents are out of authorized bounds 0-99:
- DB_Date.baddateformat: The date has a bad format:

Note: There is no months and days translation messages. The months and days will be taken directly from PHP setting the locale parameter.


III. Reference:


3.1. Contructor:

DB_Date(mixed $time)
$time contains the time information to setup the instance.
If $time is null, the instance is not initialized (no time, all in 0).
If $time in an integer, the instance is initialized with a unix timestamp.
If $time is 'N', the instance is initialized with the current timestamp (Now).
If $time is a string, the instance is initialized with the compiled time from the string. If any error happens, an exception is thrown.
If $time is a DB_Date instance, if will copy this date into the new instance.
If $time is not recognized, an exception will be thrown.


3.2. Attributes:

Only the ancestors ones.


3.3. Methods:


public void static setDefaultZone(integer $zone)
Will fix the default time zone with the one you specify explicitely. By default, the default time zone is the system one.
  • $zone: Integer, from -12 to +12. Indicates the time zone to add to any date to create if it does not contains a time zone in its format.
If the time zone is not valid, a DB_DateException will be thrown.

public integer static getDefaultZone()
Returns the default time zone, from -12 to +12.

public void static setDefaultFormat(string $format, string $dateformat, string $timeformat)
Will fix the default formats to print the timestamp, date or time respectively.
The default formats are:
YYYY-MM-DDTHH24:MI:SS.CZ for the timestamp
YYYY-MM-DD for the date
HH24:MI:SS for the time
  • $format: string containing the timestamp format. If it is null, the format will not be changed.
  • $dateformat: string containing the date format. If it is null, the format will not be changed.
  • $timeformat: string containing the time format. If it is null, the format will not be changed.

public string static getDefaultFormat()
Returns the default formats of timestamp, date and time in an array:
array(
'timestamp' => ,
'date' =>
,
'time' => ''
);

public DB_Date getClone()
Returns a clone copy of this date with the same timestamp. This method is the same as PHP clone operator:
$D = new DB_Date();
$E = clone $D;
$E = $D->getClone(); // identical to clone

public (this) setDate(mixed $time)
Will set the instance with the specified date. The date has the same format as the constructor.
$time contains the time information to setup the instance.
If $time is null, the instance is not initialized (no time, all in 0).
If $time in an integer, the instance is initialized with a unix timestamp.
If $time is 'N', the instance is initialized with the current timestamp (Now).
If $time is a string, the instance is initialized with the compiled time from the string. If any error happens, an exception is thrown.
If $time is a DB_Date instance, if will copy this date into the new instance.
If $time is not recognized, an exception will be thrown.
Returns the object reference to chain the methods.

public (this) copy(DB_Date $date)
Will copy the value of $date into this date instance.
  • $date: instance of DB_Date.
If $date is not an instance of DB_Date, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setNow()
Set the instance to the current timestamp.
Returns the object reference to chain the methods.

public (this) setUnixTime(integer $ut)
  • $ut: Integer, the unix time stamp.
Will fix the date/time of the instance to the specified value.
Cents are set to zero, and the timezone is forced to the default one.
Returns the object reference to chain the methods.

public integer getUnixTime()
Returns the unix time stamp of the instance, adjusted with the time zone.
If the date is out of unix time stamp bounds, an exception will be thrown: DB_DateException.

public (this) setYear(integer $year)
  • $year: Integer, [0..9999]. The year to assign to the instance.
If the year is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setMonth(integer $month)
  • $month: Integer, [1..12]. The month to assign to the instance.
If the month is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public void setDay(integer $day)
  • $day: Integer, [1..31]. The day to assign to the instance.
If the year and the months have not been set, an exception will be thrown: DB_DateException.
If the day does not exists in this month and year, an exception will be thrown: DB_DateException.
If the day is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setHour(integer $hour)
  • $hour: Integer, [0..23]. The hour to assign to the instance.
If the hour is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setMinute(integer $minute)
  • $minute: Integer, [0..59]. The minutes to assign to the instance.
If the minutes are not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setSecond(integer $second)
  • $second: Integer, [0..59]. The seconds to assign to the instance.
If the seconds are not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setCent(integer $cent)
  • $cent: Integer, [0..99]. The cents to assign to the instance.
If the cents are not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public (this) setZone(integer $zone)
  • $zone: Integer, [-12..+12]. The time zone to assign to the instance.
If the time zone is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public boolean checkDate()
Check if the date in the instance is valid.
Returns true if the date is valid, or false.

public boolean checkTime()
Check if the time in the instance is valid.
Returns true if the time is valid, or false.

public void setDateString(string $datestring)
  • $datestring: String, contains the date to assign to the instance.
The string is a standard date with the same format you can give to the class constructor.
If the date is not valid, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public string getDateFormat(string $format)
  • $format: String, contains the format to create the string date.
You can use one of the following letters for the date formating. Any not recognized letter will be used as it is written.

Y: Year, 4 digits, start with 0 if needed.
m: Month, 2 digits, start with 0 if needed.
d: Day, 2 digits, start with 0 if needed.
H: Hour, 2 digits, 0-24 format, start with 0 if needed.
i: Minutes, 2 digits, start with 0 if needed.
s: Seconds, 2 digits, start with 0 if needed.
c: Cents, 2 digits, start with 0 if needed.
Z: Time zone, -12 to +12, or Z if it is UTC zone.

public void setDateFormat(string $format, string $datestring)
  • $format: String, contains the format to analyze.
  • $datestring: String, contains the date itself with the specified format.
The knows letters are the same as getDateFormat.
If the date cannot be read or there is any error, an exception will be thrown: DB_DateException.
Returns the object reference to chain the methods.

public integer getYear()
Returns the year as an integer.
If the instance does not contains a date, 0 is returned.

public integer getMonth()
Returns the month as an integer.
If the instance does not contains a date, 0 is returned.

public integer getMaxMonthDays()
Returns the number of days in the year/month contained in the instance.
If the instance does not contains a date, 0 is returned.

public integer getDay()
Returns the day of the month as an integer.
If the instance does not contains a date, 0 is returned.

public integer getWeekDay()
Returns the day number of the week, calculated with the Zeller algorithm. 0 is sunday, 1 is monday ... 6 is saturday.
If the instance does not contains a date, 0 is returned.

public integer getHour()
Returns the hour as an integer.

public integer getMinute()
Returns the minutes as an integer.

public integer getSecond()
Returns the seconds as an integer.

public integer getCent()
Returns the cents as an integer.

public integer getZone()
Returns the time zone as an integer.

public boolean diff(DB_Date $date)
  • $date: instance of DB_Date, contains the date to make a difference.
Returns an array of the sign of the difference, the number of days and the number of cents of difference between the 2 dates:
return array(
'neg' => true/false,
'days' => integer,
'cents' => integer
);
The 'neg' attribute denotes a negative quantity of time, if the parameter $date is greater that the one in the instance.
The quantity of days between the dates is calculated in base of the Julian day of each date.
The quantity of cents between the dates is calculated directly with the formula
cents = (d1.hour - d2.hour - d1.zone + d2.zone) * 24*360000 + (d1.minute - d2.minute) * 6000 + (d1.second - d2.second) * 100 + (d1.cent - d2.cent);
If the difference of cents is greater than 24 hours, the number of days are adjusted too.

public boolean equal(DB_Date $date)
  • $date: instance of DB_Date, contains the date to compare.
Returns true if the date of the instance is equal to $date.

public boolean inf(DB_Date $date)
  • $date: instance of DB_Date, contains the date to compare.
Returns true if the date of the instance is strictly inferior to $date.

public boolean infequal(DB_Date $date)
  • $date: instance of DB_Date, contains the date to compare.
Returns true if the date of the instance is inferior or equal to $date.

public boolean sup(DB_Date $date)
  • $date: instance of DB_Date, contains the date to compare.
Returns true if the date of the instance is strictly superior to $date.

public boolean supequal(DB_Date $date)
  • $date: instance of DB_Date, contains the date to compare.
Returns true if the date of the instance is superior or equal to $date.

public boolean between(DB_Date $datebegin, DB_Date $dateend)
  • $datebegin: instance of DB_Date, contains the initial date to compare.
  • $dateend: instance of DB_Date, contains the final date to compare.
Returns true if the date of the instance is between $datebegin and $dateend included.

public void addYears(integer $offset)
  • $offset: Integer positive or negative. Number of years to add or substract to this date.
Returns the object reference to chain the methods.

public void addMonths(integer $offset)
  • $offset: Integer positive or negative. Number of months to add or substract to this date.
Returns the object reference to chain the methods.

public void addDays(integer $offset)
  • $offset: Integer positive or negative. Number of days to add or substract to this date.
Returns the object reference to chain the methods.

public void addHours(integer $offset)
  • $offset: Integer positive or negative. Number of hours to add or substract to this date.
Returns the object reference to chain the methods.

public void addMinutes(integer $offset)
  • $offset: Integer positive or negative. Number of minutes to add or substract to this date.
Returns the object reference to chain the methods.

public void addSeconds(integer $offset)
  • $offset: Integer positive or negative. Number of seconds to add or substract to this date.
Returns the object reference to chain the methods.

public void addCents(integer $offset)
  • $offset: Integer positive or negative. Number of cents to add or substract to this date.
Returns the object reference to chain the methods.

public string __toString()
Returns the date as a string, formatted with the default format.
If the instance contains a full timestamp, the full ISO format will be used.
If the instance contains only time, the time format will be used.
If the instance contains only a date (time set to 00:00:00.00), the date format will be used.
The programmer can set its own default formats.