# sfDateTimePlugin plugin

## Overview

This plugin will add a date manipulation library to the symfony framework.
The library manipulates timestamp values, allowing you to quickly translate a date into another date based on an infinite number of operations.
The library contains a base add function, which handles all cases of a single date manipulation.
It also contains a large number of other functions based on the add function, which faciliate more complicated operations.
Finally, the library contains an instantiable class, which provides an interface hook into the main library allowing chainable date manipulation operations for more readable code.

## Installation

To install sfDateTimePlugin:

    
    symfony plugin-install http://plugins.symfony-project.com/sfDateTimePlugin
    

Clear your cache

    
    symfony cc
    

You're done!

## Usage

Examples which dump their results to a datetime.

    
    [php]
    <?php
    
    // defaults to now
    $dt = new sfDate();
    // accepts existing sfDate object
    $dt = new sfDate($dt);
    // accepts a timestamp integer, like from time() or mktime()
    $dt = new sfDate(1176856745);
    // parses date from a string using strtotime
    $dt = new sfDate('2007-04-17 19:39:05');
    
    echo $dt->firstDayOfWeek()->tomorrow()->dump();
    // => 2007-04-16 19:39:05
    echo $dt->addYear()->subtractQuarter()->dump();
    // => 2008-01-16 19:39:05
    echo $dt->finalDayOfQuarter()->clearTime()->dump();
    // => 2008-03-31 00:00:00
    echo $dt->finalDayOfYear()->subtractWeek(4)->addDay(5)->dump();
    // => 2008-12-08 00:00:00
    echo $dt->reset()->dump();
    // => 2007-04-17 19:39:05
    

The I18N date helpers are integrated directly into the library.

    
    [php]
    <!-- <?php use_helper('Date') ?> is not necessary in this case -->
    
    Next sunday in your language: <?php echo sfDate::getInstance()->firstDayOfWeek()->addWeek()->date() ?>
    Last thursday in your language: <?php echo sfDate::getInstance()->previousDay(sfTime::THURSDAY)->date() ?>
    Now in your language: <?php echo sfDate::getInstance()->datetime() ?>
    

## Documentation

### Constants

Constants are available through the sfTime class (as in sfTime::CONSTANT_NAME):

  * Units of time
    * SECOND
    * MINUTE
    * HOUR
    * DAY
    * WEEK
    * MONTH
    * QUARTER
    * YEAR
    * DECADE
    * CENTURY
    * MILLENIUM
  * Days of the week
    * SUNDAY
    * MONDAY
    * TUESDAY
    * WEDNESDAY
    * THURSDAY
    * FRIDAY
    * SATURDAY
  * Months of the year
    * JANUARY
    * FEBRUARY
    * MARCH
    * APRIL
    * MAY
    * JUNE
    * JULY
    * AUGUST
    * SEPTEMBER
    * OCTOBER
    * NOVEMBER
    * DECEMBER

### Functions

The following functions are available to an instantiated sfDate object, and are chainable:

	* add
		* parameters
			* number of units
		* unit of time
	* subtract
		* parameters
			* number of units
		* unit of time
	* add functions
		* format: add<Time> (eg. addDay, addWeek, addYear)
		* parameters
			* number of units
	* subtract functions
		* format: subtract<Time> (eg. subtractDay, subtractWeek, subtractYear)
		* parameters
			* number of units
	* first functions
		* format: firstDayOf<Time> (eg. firstDayOfWeek, firstDayOfMonth, firstDayOfYear)
	* final functions
		* format: finalDayOf<Time> (eg. finalDayOfWeek, finalDayOfMonth, finalDayOfYear)
	* next functions
		* format: next<Time> (eg. nextDay, nextMonth)
		* parameters
			* period (day of week, month of year)
	* previous functions
		* format: previous<Time> (eg. previousDay, previousMonth)
		* parameters
			* period (day of week, month of year)
	* tomorrow
	* yesterday
	* clearTime
	* clearDate
	* now
	* set
	* reset

The following functions are available to an instantiated sfDate object, and are not chainable:

	* get
		* returns the timestamp
	* dump
		* returns the timestamp formatted as a datetime
		* useful in Propel (database) expressions
	* format
		* returns the timestamp formatted according to the php function, date
		* parameters
			* format (see [date](http://php.net/date))
		* not I18N compatible
	* date
		* returns the timestamp formatted according to the symfony helper, format_date
		* I18N compatible
	* datetime
		* returns the timestamp formatted according to the symfony helper, format_datetime
		* I18N compatible
	* cmp
		* compares two dates
	* diff
		* subtracts two dates, in seconds
	* retrieve
		* retrieve a component of the date
		* parameters
			* unit of time
	
The following functions are available to the sfDate class, and are chainable:

	* getInstance
		* static
		* returns a newly instantiated object


### Notes

  **NOTE**: All parameters are optional and default to logical values (1 for numbers, DAY for units of time, SUNDAY for days of week, JANUARY for months of year).

  **NOTE**: When using the sfTime function library itself, the first parameter of every function is a timestamp. When using an instantiated sfDate, the timestamp parameter is automatically passed in.

## License

For the full copyright and license information, please view the LICENSE
file that was distributed with this source code.