Clientbase
/
PhpSpreadsheet
mirror of https://github.com/basemaster/PhpSpreadsheet.git
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update Doc Blocks to Discourage Use of Unix Timestamps (#2350) 

* Update Doc Blocks to Discourage Use of Unix Timestamps

This was suggested by issue #2347. Unix timestamps have clear disadvantages compared with the alternate methods of supplying date and time to PhpSpreadsheet - DateTime objects, Excel date time fields, and strings. In particular, Unix timestamp is not Y2038-safe on a 32-bit system, and it reflects the time in UTC, which may come as a surprise to the end-user (as it did in the cited issue). The alternate methods do not come with such baggage. This change updates some doc blocks to note that Unix timestamps are discoburage (N.B. - not deprecated). No executable code is changed.

* Document in Code As Well as Commmit Message

Per suggestion from @PowerKiKi.

* Missed One DocBlock

Including it now.

Co-authored-by: Adrien Crivelli <adrien.crivelli@gmail.com>
This commit is contained in:
oleibman 2021-11-04 08:12:47 -07:00 committed by GitHub
parent da5c2b1c22
commit b1c9f0a1bc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 10 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/PhpSpreadsheet/Calculation/Functions.php
View File

@ -15,12 +15,13 @@ class Functions
*/
const M_2DIVPI = 0.63661977236758134307553505349006;
/** constants */
const COMPATIBILITY_EXCEL = 'Excel';
const COMPATIBILITY_GNUMERIC = 'Gnumeric';
const COMPATIBILITY_OPENOFFICE = 'OpenOfficeCalc';
/** Use of RETURNDATE_PHP_NUMERIC is discouraged - not 32-bit Y2038-safe, no timezone. */
const RETURNDATE_PHP_NUMERIC = 'P';
/** Use of RETURNDATE_UNIX_TIMESTAMP is discouraged - not 32-bit Y2038-safe, no timezone. */
const RETURNDATE_UNIX_TIMESTAMP = 'P';
const RETURNDATE_PHP_OBJECT = 'O';
const RETURNDATE_PHP_DATETIME_OBJECT = 'O';

11
src/PhpSpreadsheet/Shared/Date.php
View File

@ -163,7 +163,7 @@ class Date
* @param float|int $excelTimestamp MS Excel serialized date/time value
* @param null|DateTimeZone|string $timeZone The timezone to assume for the Excel timestamp,
* if you don't want to treat it as a UTC value
* Use the default (UST) unless you absolutely need a conversion
* Use the default (UTC) unless you absolutely need a conversion
*
* @return DateTime PHP date/time object
*/
@ -206,11 +206,13 @@ class Date
/**
* Convert a MS serialized datetime value from Excel to a unix timestamp.
* The use of Unix timestamps, and therefore this function, is discouraged.
* They are not Y2038-safe on a 32-bit system, and have no timezone info.
*
* @param float|int $excelTimestamp MS Excel serialized date/time value
* @param null|DateTimeZone|string $timeZone The timezone to assume for the Excel timestamp,
* if you don't want to treat it as a UTC value
* Use the default (UST) unless you absolutely need a conversion
* Use the default (UTC) unless you absolutely need a conversion
*
* @return int Unix timetamp for this date/time
*/
@ -223,7 +225,8 @@ class Date
/**
* Convert a date from PHP to an MS Excel serialized date/time value.
*
* @param mixed $dateValue Unix Timestamp or PHP DateTime object or a string
* @param mixed $dateValue PHP DateTime object or a string - Unix timestamp is also permitted, but discouraged;
* not Y2038-safe on a 32-bit system, and no timezone info
*
* @return bool|float Excel date/time value
* or boolean FALSE on failure
@ -262,6 +265,8 @@ class Date
/**
* Convert a Unix timestamp to an MS Excel serialized date/time value.
* The use of Unix timestamps, and therefore this function, is discouraged.
* They are not Y2038-safe on a 32-bit system, and have no timezone info.
*
* @param int $unixTimestamp Unix Timestamp
*