Frames Modems Help Home Page Chipsets Search No Frames
Diary Entries See also Site Info & Diary.
26 March 2004 Documenting the php PEAR Date Class...
 

(Warning: short bitch follows): This page suggests one of the problems with the Open Source movement. All I wanted to do was discover the year, month & day of a date 100 days before today. In the time that it has taken me to research all this I could have written my own Class.

This page seeks to document (below) one of the un-documented Classes within PEAR--the “PHP Extension and Application Repository”, one of the hidden extras of PHP--namely the Date Class.

If you look at the PEAR manual for Date and Time you will find page after page documenting the Calendar Class, and absolutely nothing about the Date Class. Also, the class-maintainers seem to have their heads so far up their arses that they cannot see the second-hand on the clock. It’s very dispiriting, and must be wasting a lot of time for a lot of people. It’s a shame that the writers & maintainers of this Class do not realise that, whilst it goes undocumented, for most people it may as well not exist and that, therefore, all their work may as well have been thrown down the toilet.

I do not have the time to do a full job, either, but will attempt to at least list all the functions of the Class and to give any specifics as I find them.

 

PEAR is a Good Thing. No point in continually reinventing the wheel. The manual for the versions of PHP up to at least version 4.2.2 mention PEAR but only document the base Classes, which are not intended to be used directly. I think. For a long time, I was ignorant of the fact that PEAR classes were bundled with PHP. The PEAR Package Manager has been bundled with PHP since php 4.3, and the intention of that is to make it a doddle to install any package of pre-written PEAR Classes that you wish. Have a look at this sitepoint article on PEAR if, like myself, you need to use the PEAR Installer to get the Package Manager to get (or update--there is a recent bug in the Date package) the packages. For myself it was: 

lynx -source http://pear.php.net/go-pear | php

...from the Linux command-line logged in as root, but check out the article-link above, because your case is more than likely to be different. There is information to gather first:

  1. Installation Prefix
  2. Binaries (scripts) Location
  3. PHP Code Directory
  4. Documentation Base Directory
  5. Data Base Directory
  6. Test Directory

These are all directory (folder) names. I found phpinfo() to be useful here. It’s necessary to check that PEAR is implemented (make sure that the Configure command has '--with-pear=<the-PEAR-directory>' & that the Configuration : PHP Core : include_path has the same directory. Then, under PHP Variables is _SERVER["DOCUMENT_ROOT"]. I only needed to change the Documentation Base Directory as everything else was the same as the defaults. The routines download, install & configure base PEAR classes, plus install the Package Manager. It was a doddle to do. At this point, from the command line: 

pear
pear config-show
pear config-help <optioname>
pear remote-list
pear install <package>

..are good options to try. With hindsight, the one change that I would have made would be to create a download directory within the Binaries (scripts) folder, and to have located myself within that directory, since all the .tgz files are dropped by default wherever you are. Also, I first downloaded all packages and installed-from-file. Which turned out to be a mistake, as the Package Manager does not check for the pre-existence of up-to-date packages on disk but downloads ALL not-installed dependant packages regardless. A bit of a bug.

OK, on to the Date class:

 

The PEAR Date() class:

Overview: the idea is:

  1. Create one-or-more instances of the Class
  2. Do whatever operations, calculations to the object as needed
  3. Recover the info that is needed

eg: 

<?php
  require_once 'Date.php';                // will also include dependant files

  $_DATE_TIMEZONE_DEFAULT='GB';           // see TimeZone.php for legal values
  $today = new Date();                    // by default, today’s date
  $today->subtractSeconds( 100 * 86400 ); // 100 days

  $day   = $today->getDay();
  $month = $today->getMonth();
  $year  = $today->getYear();
?>

All very simple, once you have the overview of each class function.

Function groupings:

  1. Constructor
  2. Operations
  3. Retrieve info
  4. TimeZone.php
    5. (+ a possible bug)
 

Function groupings: Constructor: 

  $today     = new Date();                    // by default, today’s date
  $copy      = new Date( $today );            // a copy of a Date object
  $iso_8601  = new Date( $iso_8601_string );  // ISO_8601 format string
  $timestamp = new Date( $timestamp_string ); // TIMESTAMP format string
  $unixtime  = new Date( $unixtime_string );  // UNIXTIME format string

Note on use of format strings during instantiation: the constructor says: “This regex is very loose and accepts almost any butchered format you could throw at it. e.g. 2003-10-07 19:45:15 and 2003-10071945:15 are the same thing in the eyes of this regex, even though the latter is not a valid ISO 8601 date.”

Class variables; the following are internally all integers: 

  $Date->year
  $Date->month
  $Date->day
  $Date->hour
  $Date->minute
  $Date->second
  $Date->tz      // time-zone object; see TimeZone.php

The following will be documented here, for space considerations: 

  $date->format( $format_string )
  $date->getDate( $format_constant = DATE_FORMAT_ISO )
  $date->setDate( $date_string, $format_constant = DATE_FORMAT_ISO )

$date->format( $format_string ):

This returns a string date & time representation of the $date Date object’s date/time which varies according to the supplied string $format_string, which itself has a format similar to strftime(): 

  %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 same as "%m/%d/%y"
  %e day of month, single digit (range 0 to 31)
  %E number of days since unspecified epoch (integer, Date_Calc::dateToDays())
  %H hour as decimal number (00 to 23)
  %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 dst-corrected time zone offset expressed as "+/-HH:MM"
  %o raw 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, same as "%I:%M:%S %p"
  %R time in 24-hour notation, same as "%H:%M"
  %S seconds as a decimal number (00 to 59)
  %t tab character (\t)
  %T current time, same as "%H:%M:%S"
  %w weekday as decimal (0 = Sunday)
  %U week number of current year, first Sunday as first week
  %y year as decimal (range 00 to 99)
  %Y year as decimal including century (range 0000 to 9999)
  %% literal '%'

$date->getDate( $format_constant = DATE_FORMAT_ISO ):

Returns a string date & time representation of the $date Date object in a format decided by the supplied constant $format_constant, which itself is one of the following Class define()s: 

  DATE_FORMAT_ISO          : YYYY-MM-DD HH:MM:SS
  DATE_FORMAT_ISO_BASIC    : YYYYMMSSTHHMMSS(Z|(+/-)HHMM)?
  DATE_FORMAT_ISO_EXTENDED : YYYY-MM-SSTHH:MM:SS(Z|(+/-)HH:MM)?
  DATE_FORMAT_TIMESTAMP    : YYYYMMDDHHMMSS
  DATE_FORMAT_UNIXTIME     : long int, seconds since the Unix epoch

$date->setDate( $date_string ):
$date->setDate( $date_string, $format_constant = DATE_FORMAT_ISO ):

Sets the date & time of the $date Date object based on the input string $date_string and format constant $format_constant, which latter is specified by the DATE_FORMAT_* constants (above). The function comment says about $format_constant that “This parameter isn't really needed anymore, but you could use it to force DATE_FORMAT_UNIXTIME”.

 

Function groupings: Operations

Do something to the instantiated $date Date object: 

  $date->addSeconds( $sec )    // $sec is converted to integer
  $date->addSpan( $span )      // $span = a Date_Span object
  $date->convertTZ( $tz )      // convert both date + time-zone to new time-zone
  $date->convertTZbyID( $id )  // $id = a (string) Date_TimeZone id
  $date->copy( $another_date )
  $date->setDate( $date_string, $format_constant = DATE_FORMAT_ISO ) - see Constructor
  $date->setDay( $d )          // $d  = integer (1-31) else = 1
  $date->setHour( $h )         // $h  = integer (0-23) else = 0
  $date->setMinute( $m )       // $m  = integer (0-59) else = 0
  $date->setMonth( $m )        // $m  = integer (1-12) else = 1
  $date->setSecond( $s )       // $s  = integer (0-59) else = 0
  $date->setTZ()               // set to default time-zone, no date-change
  $date->setTZ( $tz )          // $tz = a Date_TimeZone object; see also convertTZ()
  $date->setTZbyID()           // set to default time-zone, no date-change
  $date->setTZbyID( $id )      // $id = a (string) Date_TimeZone id
  $date->setYear( $y )         // $y  = integer (0-9999) else = 0
  $date->subtractSeconds( $sec )
  $date->subtractSpan( $span ) // $span = a Date_Span object
  $date->toUTC()               // convert both date + time-zone to UTC
  $date->toUTCbyOffset()
 

Function groupings: Retrieve info: 

  $date->after( $when )        // TRUE/FALSE; $when = a Date object
  $date->before( $when )       // TRUE/FALSE; $when = a Date object
  $date->compare( $d1, $d2 )   // $d1, $d2 = Date objects
                               //  0 if the dates are equal
                               // -1 if d1 is before d2
                               //  1 if d1 is after d2
  $date->equals( $when )       // TRUE/FALSE; $when = a Date object
  $date->format( $format_string ) - see Constructor
  $date->getDate( $format_constant = DATE_FORMAT_ISO ) - see Constructor
  $date->getDay()              // integer
  $date->getDayName( TRUE )    // full name string
  $date->getDayName( FALSE, $length = 3 ) // (default) abbreviated
  $date->getDayOfWeek()        // integer (0=Sunday)
  $date->getDaysInMonth()      // integer
  $date->getHour()             // integer
  $date->getJulianDate()       // integer
  $date->getMinute()           // integer
  $date->getMonth()            // integer (supposed to be - string for me)
  $date->getMonthName( TRUE )  // full name string; default: abbreviated
  $date->getNextDay()          // returns a Date object
  $date->getNextWeekday()      // returns a Date object
  $date->getPrevDay()          // returns a Date object
  $date->getPrevWeekday()      // returns a Date object
  $date->getSecond()           // integer
  $date->getTime()             // returns time in Unix time() format
  $date->getQuarterOfYear()    // integer
  $date->getWeekOfYear()       // integer
  $date->getWeeksInMonth()     // integer
  $date->getYear()             // integer
  $date->inDaylightTime()      // TRUE if DST is in effect/FALSE; see 12 Apr for a possible bug
  $date->isFuture()            // TRUE/FALSE;
  $date->isLeapYear()          // TRUE/FALSE;
  $date->isPast()              // TRUE/FALSE;