alex
/
PhpSpreadsheet
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clarify documentation about `DateTime` 

Closes #164
This commit is contained in:
Adrien Crivelli 2017-07-30 22:25:24 +02:00
parent 2e59885895
commit fd4445f4aa
No known key found for this signature in database
GPG Key ID: B182FD79DC6DE92E
1 changed files with 70 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
docs/topics/calculation-engine.md
View File

@ -90,7 +90,7 @@ calculated values, or force recalculation in Excel2003.
### Excel functions that return a Date and Time value ### Excel functions that return a Date and Time value
Any of the Date and Time functions that return a date value in Excel can Any of the Date and Time functions that return a date value in Excel can
return either an Excel timestamp or a PHP timestamp or date object. return either an Excel timestamp or a PHP timestamp or `DateTime` object.
It is possible for scripts to change the data type used for returning It is possible for scripts to change the data type used for returning
date values by calling the date values by calling the
@ -103,9 +103,9 @@ method:
where the following constants can be used for `$returnDateType`: where the following constants can be used for `$returnDateType`:
- `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_PHP_NUMERIC` - `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_PHP_NUMERIC`
- `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_PHP_OBJECT` - `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_PHP_OBJECT`
- `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_EXCEL` - `\PhpOffice\PhpSpreadsheet\Calculation\Functions::RETURNDATE_EXCEL`
The method will return a Boolean True on success, False on failure (e.g. The method will return a Boolean True on success, False on failure (e.g.
if an invalid value is passed in for the return date type). if an invalid value is passed in for the return date type).
@ -117,11 +117,11 @@ method can be used to determine the current value of this setting:
$returnDateType = \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(); $returnDateType = \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType();
``` ```
The default is RETURNDATE\_PHP\_NUMERIC. The default is `RETURNDATE_PHP_NUMERIC`.
#### PHP Timestamps #### PHP Timestamps
If RETURNDATE\_PHP\_NUMERIC is set for the Return Date Type, then any If `RETURNDATE_PHP_NUMERIC` is set for the Return Date Type, then any
date value returned to the calling script by any access to the Date and date value returned to the calling script by any access to the Date and
Time functions in Excel will be an integer value that represents the Time functions in Excel will be an integer value that represents the
number of seconds from the PHP/Unix base date. The PHP/Unix base date number of seconds from the PHP/Unix base date. The PHP/Unix base date
@ -131,15 +131,15 @@ while a value of +3600 would be 01:00 hrs on 1st January 1970. This
gives PHP a date range of between 14th December 1901 and 19th January gives PHP a date range of between 14th December 1901 and 19th January
2038. 2038.
#### PHP DateTime Objects #### PHP `DateTime` Objects
If the Return Date Type is set for RETURNDATE\_PHP\_NUMERIC, then any If the Return Date Type is set for `RETURNDATE_PHP_OBJECT`, then any
date value returned to the calling script by any access to the Date and date value returned to the calling script by any access to the Date and
Time functions in Excel will be a PHP date/time object. Time functions in Excel will be a PHP `DateTime` object.
#### Excel Timestamps #### Excel Timestamps
If RETURNDATE\_EXCEL is set for the Return Date Type, then the returned If `RETURNDATE_EXCEL` is set for the Return Date Type, then the returned
date value by any access to the Date and Time functions in Excel will be date value by any access to the Date and Time functions in Excel will be
a floating point value that represents a number of days from the Excel a floating point value that represents a number of days from the Excel
base date. The Excel base date is determined by which calendar Excel base date. The Excel base date is determined by which calendar Excel
@ -157,8 +157,8 @@ Excel date values by calling the
where the following constants can be used for `$baseDate`: where the following constants can be used for `$baseDate`:
- \PhpOffice\PhpSpreadsheet\Shared\Date::CALENDAR\_WINDOWS\_1900 - `\PhpOffice\PhpSpreadsheet\Shared\Date::CALENDAR_WINDOWS_1900`
- \PhpOffice\PhpSpreadsheet\Shared\Date::CALENDAR\_MAC\_1904 - `\PhpOffice\PhpSpreadsheet\Shared\Date::CALENDAR_MAC_1904`
The method will return a Boolean True on success, False on failure (e.g. The method will return a Boolean True on success, False on failure (e.g.
if an invalid value is passed in). if an invalid value is passed in).
@ -170,31 +170,31 @@ be used to determine the current value of this setting:
$baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar(); $baseDate = \PhpOffice\PhpSpreadsheet\Shared\Date::getExcelCalendar();
``` ```
The default is CALENDAR\_WINDOWS\_1900. The default is `CALENDAR_WINDOWS_1900`.
#### Functions that return a Date/Time Value #### Functions that return a Date/Time Value
- DATE - DATE
- DATEVALUE - DATEVALUE
- EDATE - EDATE
- EOMONTH - EOMONTH
- NOW - NOW
- TIME - TIME
- TIMEVALUE - TIMEVALUE
- TODAY - TODAY
### Excel functions that accept Date and Time values as parameters ### Excel functions that accept Date and Time values as parameters
Date values passed in as parameters to a function can be an Excel Date values passed in as parameters to a function can be an Excel
timestamp or a PHP timestamp; or date object; or a string containing a timestamp or a PHP timestamp; or `DateTime` object; or a string containing a
date value (e.g. '1-Jan-2009'). PhpSpreadsheet will attempt to identify date value (e.g. '1-Jan-2009'). PhpSpreadsheet will attempt to identify
their type based on the PHP datatype: their type based on the PHP datatype:
An integer numeric value will be treated as a PHP/Unix timestamp. A real An integer numeric value will be treated as a PHP/Unix timestamp. A real
(floating point) numeric value will be treated as an Excel (floating point) numeric value will be treated as an Excel
date/timestamp. Any PHP DateTime object will be treated as a DateTime date/timestamp. Any PHP `DateTime` object will be treated as a `DateTime`
object. Any string value (even one containing straight numeric data) object. Any string value (even one containing straight numeric data)
will be converted to a date/time object for validation as a date value will be converted to a `DateTime` object for validation as a date value
based on the server locale settings, so passing through an ambiguous based on the server locale settings, so passing through an ambiguous
value of '07/08/2008' will be treated as 7th August 2008 if your server value of '07/08/2008' will be treated as 7th August 2008 if your server
settings are UK, but as 8th July 2008 if your server settings are US. settings are UK, but as 8th July 2008 if your server settings are US.
@ -202,7 +202,7 @@ However, if you pass through a value such as '31/12/2008' that would be
considered an error by a US-based server, but which is not ambiguous, considered an error by a US-based server, but which is not ambiguous,
then PhpSpreadsheet will attempt to correct this to 31st December 2008. then PhpSpreadsheet will attempt to correct this to 31st December 2008.
If the content of the string doesn’t match any of the formats recognised If the content of the string doesn’t match any of the formats recognised
by the php date/time object implementation of `strtotime()` (which can by the php `DateTime` object implementation of `strtotime()` (which can
handle a wider range of formats than the normal `strtotime()` function), handle a wider range of formats than the normal `strtotime()` function),
then the function will return a `#VALUE` error. However, Excel then the function will return a `#VALUE` error. However, Excel
recommends that you should always use date/timestamps for your date recommends that you should always use date/timestamps for your date
@ -213,28 +213,28 @@ The same principle applies when data is being written to Excel. Cells
containing date actual values (rather than Excel functions that return a containing date actual values (rather than Excel functions that return a
date value) are always written as Excel dates, converting where date value) are always written as Excel dates, converting where
necessary. If a cell formatted as a date contains an integer or necessary. If a cell formatted as a date contains an integer or
date/time object value, then it is converted to an Excel value for `DateTime` object value, then it is converted to an Excel value for
writing: if a cell formatted as a date contains a real value, then no writing: if a cell formatted as a date contains a real value, then no
conversion is required. Note that string values are written as strings conversion is required. Note that string values are written as strings
rather than converted to Excel date timestamp values. rather than converted to Excel date timestamp values.
#### Functions that expect a Date/Time Value #### Functions that expect a Date/Time Value
- DATEDIF - DATEDIF
- DAY - DAY
- DAYS360 - DAYS360
- EDATE - EDATE
- EOMONTH - EOMONTH
- HOUR - HOUR
- MINUTE - MINUTE
- MONTH - MONTH
- NETWORKDAYS - NETWORKDAYS
- SECOND - SECOND
- WEEKDAY - WEEKDAY
- WEEKNUM - WEEKNUM
- WORKDAY - WORKDAY
- YEAR - YEAR
- YEARFRAC - YEARFRAC
### Helper Methods ### Helper Methods
@ -243,7 +243,7 @@ number of other methods are available in the
\PhpOffice\PhpSpreadsheet\Shared\Date class that can help when working \PhpOffice\PhpSpreadsheet\Shared\Date class that can help when working
with dates: with dates:
#### \PhpOffice\PhpSpreadsheet\Shared\Date::ExcelToPHP($excelDate) #### \PhpOffice\PhpSpreadsheet\Shared\Date::excelToTimestamp($excelDate)
Converts a date/time from an Excel date timestamp to return a PHP Converts a date/time from an Excel date timestamp to return a PHP
serialized date/timestamp. serialized date/timestamp.
@ -251,17 +251,17 @@ serialized date/timestamp.
Note that this method does not trap for Excel dates that fall outside of Note that this method does not trap for Excel dates that fall outside of
the valid range for a PHP date timestamp. the valid range for a PHP date timestamp.
#### \PhpOffice\PhpSpreadsheet\Shared\Date::ExcelToPHPObject($excelDate) #### \PhpOffice\PhpSpreadsheet\Shared\Date::excelToDateTimeObject($excelDate)
Converts a date from an Excel date/timestamp to return a PHP DateTime Converts a date from an Excel date/timestamp to return a PHP `DateTime`
object. object.
#### \PhpOffice\PhpSpreadsheet\Shared\Date::PHPToExcel($PHPDate) #### \PhpOffice\PhpSpreadsheet\Shared\Date::PHPToExcel($PHPDate)
Converts a PHP serialized date/timestamp or a PHP DateTime object to Converts a PHP serialized date/timestamp or a PHP `DateTime` object to
return an Excel date timestamp. return an Excel date timestamp.
#### \PhpOffice\PhpSpreadsheet\Shared\Date::FormattedPHPToExcel($year, $month, $day, $hours=0, $minutes=0, $seconds=0) #### \PhpOffice\PhpSpreadsheet\Shared\Date::formattedPHPToExcel($year, $month, $day, $hours=0, $minutes=0, $seconds=0)
Takes year, month and day values (and optional hour, minute and second Takes year, month and day values (and optional hour, minute and second
values) and returns an Excel date timestamp value. values) and returns an Excel date timestamp value.
@ -979,7 +979,7 @@ Excel and in PHP.
#### DATE #### DATE
The DATE function returns an Excel timestamp or a PHP timestamp or date The DATE function returns an Excel timestamp or a PHP timestamp or `DateTime`
object representing the date that is referenced by the parameters. object representing the date that is referenced by the parameters.
##### Syntax ##### Syntax
@ -1025,7 +1025,7 @@ February 27, 2008.
**mixed** A date/time stamp that corresponds to the given date. **mixed** A date/time stamp that corresponds to the given date.
This could be a PHP timestamp value (integer), a PHP date/time object, This could be a PHP timestamp value (integer), a PHP `DateTime` object,
or an Excel timestamp value (real), depending on the value of or an Excel timestamp value (real), depending on the value of
\PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(). \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType().
@ -1093,12 +1093,12 @@ variety of different intervals, such number of years, months, or days.
**date1** First Date. **date1** First Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**date2** Second Date. **date2** Second Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**unit** The interval type to use for the calculation **unit** The interval type to use for the calculation
@ -1230,7 +1230,7 @@ A string, representing a date value.
**mixed** A date/time stamp that corresponds to the given date. **mixed** A date/time stamp that corresponds to the given date.
This could be a PHP timestamp value (integer), a PHP date/time object, This could be a PHP timestamp value (integer), a PHP `DateTime` object,
or an Excel timestamp value (real), depending on the value of or an Excel timestamp value (real), depending on the value of
\PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(). \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType().
@ -1290,7 +1290,7 @@ $retVal = call_user_func_array(
##### Notes ##### Notes
DATEVALUE uses the php date/time object implementation of `strtotime()` DATEVALUE uses the php `DateTime` object implementation of `strtotime()`
(which can handle a wider range of formats than the normal `strtotime()` (which can handle a wider range of formats than the normal `strtotime()`
function), and it is also called for any date parameter passed to other function), and it is also called for any date parameter passed to other
date functions (such as DATEDIF) when the parameter value is a string. date functions (such as DATEDIF) when the parameter value is a string.
@ -1317,7 +1317,7 @@ integer ranging from 1 to 31.
**datetime** Date. **datetime** Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
##### Return Value ##### Return Value
@ -1371,12 +1371,12 @@ accounting systems.
**date1** First Date. **date1** First Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**date2** Second Date. **date2** Second Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**method** A boolean flag (TRUE or FALSE) **method** A boolean flag (TRUE or FALSE)
@ -1453,7 +1453,7 @@ Excel `TRUE()` and `FALSE()` functions are used instead.
#### EDATE #### EDATE
The EDATE function returns an Excel timestamp or a PHP timestamp or date The EDATE function returns an Excel timestamp or a PHP timestamp or `DateTime`
object representing the date that is the indicated number of months object representing the date that is the indicated number of months
before or after a specified date (the start\_date). Use EDATE to before or after a specified date (the start\_date). Use EDATE to
calculate maturity dates or due dates that fall on the same day of the calculate maturity dates or due dates that fall on the same day of the
@ -1467,7 +1467,7 @@ month as the date of issue.
**baseDate** Start Date. **baseDate** Start Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**months** Number of months to add. **months** Number of months to add.
@ -1480,7 +1480,7 @@ value yields a past date.
**mixed** A date/time stamp that corresponds to the basedate + months. **mixed** A date/time stamp that corresponds to the basedate + months.
This could be a PHP timestamp value (integer), a PHP date/time object, This could be a PHP timestamp value (integer), a PHP `DateTime` object,
or an Excel timestamp value (real), depending on the value of or an Excel timestamp value (real), depending on the value of
\PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(). \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType().
@ -1526,7 +1526,7 @@ the Analysis ToolPak.
#### EOMONTH #### EOMONTH
The EOMONTH function returns an Excel timestamp or a PHP timestamp or The EOMONTH function returns an Excel timestamp or a PHP timestamp or
date object representing the date of the last day of the month that is `DateTime` object representing the date of the last day of the month that is
the indicated number of months before or after a specified date (the the indicated number of months before or after a specified date (the
start\_date). Use EOMONTH to calculate maturity dates or due dates that start\_date). Use EOMONTH to calculate maturity dates or due dates that
fall on the last day of the month. fall on the last day of the month.
@ -1539,7 +1539,7 @@ fall on the last day of the month.
**baseDate** Start Date. **baseDate** Start Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**months** Number of months to add. **months** Number of months to add.
@ -1553,7 +1553,7 @@ value yields a past date.
**mixed** A date/time stamp that corresponds to the last day of basedate **mixed** A date/time stamp that corresponds to the last day of basedate
+ months. + months.
This could be a PHP timestamp value (integer), a PHP date/time object, This could be a PHP timestamp value (integer), a PHP `DateTime` object,
or an Excel timestamp value (real), depending on the value of or an Excel timestamp value (real), depending on the value of
\PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(). \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType().
@ -1607,7 +1607,7 @@ an integer, ranging from 0 (12:00 A.M.) to 23 (11:00 P.M.).
**datetime** Time. **datetime** Time.
An Excel date/time value, PHP date timestamp, PHP date object, or a An Excel date/time value, PHP date timestamp, PHP `DateTime` object, or a
date/time represented as a string. date/time represented as a string.
##### Return Value ##### Return Value
@ -1665,7 +1665,7 @@ given as an integer, ranging from 0 to 59.
**datetime** Time. **datetime** Time.
An Excel date/time value, PHP date timestamp, PHP date object, or a An Excel date/time value, PHP date timestamp, PHP `DateTime` object, or a
date/time represented as a string. date/time represented as a string.
##### Return Value ##### Return Value
@ -1723,7 +1723,7 @@ integer ranging from 1 to 12.
**datetime** Date. **datetime** Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
##### Return Value ##### Return Value
@ -1779,12 +1779,12 @@ a specific term.
**startDate** Start Date of the period. **startDate** Start Date of the period.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**endDate** End Date of the period. **endDate** End Date of the period.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**holidays** Optional array of Holiday dates. **holidays** Optional array of Holiday dates.
@ -1831,7 +1831,7 @@ There are no parameters for the `NOW()` function.
**mixed** A date/time stamp that corresponds to the current date and **mixed** A date/time stamp that corresponds to the current date and
time. time.
This could be a PHP timestamp value (integer), a PHP date/time object, This could be a PHP timestamp value (integer), a PHP `DateTime` object,
or an Excel timestamp value (real), depending on the value of or an Excel timestamp value (real), depending on the value of
\PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType(). \PhpOffice\PhpSpreadsheet\Calculation\Functions::getReturnDateType().
@ -1862,7 +1862,7 @@ given as an integer, ranging from 0 to 59.
**datetime** Time. **datetime** Time.
An Excel date/time value, PHP date timestamp, PHP date object, or a An Excel date/time value, PHP date timestamp, PHP `DateTime` object, or a
date/time represented as a string. date/time represented as a string.
##### Return Value ##### Return Value
@ -1934,7 +1934,7 @@ modified to return a value between 0 and 6.
**datetime** Date. **datetime** Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
**method** An integer flag (values 0, 1 or 2) **method** An integer flag (values 0, 1 or 2)
@ -2012,7 +2012,7 @@ The YEAR function returns the year of a date.
**datetime** Date. **datetime** Date.
An Excel date value, PHP date timestamp, PHP date object, or a date An Excel date value, PHP date timestamp, PHP `DateTime` object, or a date
represented as a string. represented as a string.
##### Return Value ##### Return Value