Update Doc Blocks to Discourage Use of Unix Timestamps

This was suggested by issue PHPOffice#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.

src/PhpSpreadsheet/Calculation/Functions.php

@@ -14,12 +14,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. */
     const RETURNDATE_PHP_NUMERIC = 'P';
+    /** Use of RETURNDATE_UNIX_TIMESTAMP is discouraged. */
     const RETURNDATE_UNIX_TIMESTAMP = 'P';
     const RETURNDATE_PHP_OBJECT = 'O';
     const RETURNDATE_PHP_DATETIME_OBJECT = 'O';

src/PhpSpreadsheet/Shared/Date.php

@@ -163,7 +163,7 @@ private static function validateTimeZone($timeZone)
      * @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,12 @@ public static function excelToDateTimeObject($excelTimestamp, $timeZone = null)
 
     /**
      * Convert a MS serialized datetime value from Excel to a unix timestamp.
+     * The use of Unix timestamps, and therefore this function, is discouraged.
      *
      * @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 +224,7 @@ public static function excelToTimestamp($excelTimestamp, $timeZone = null)
     /**
      * 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
      *
      * @return bool|float Excel date/time value
      *                                  or boolean FALSE on failure
@@ -262,6 +263,7 @@ public static function dateTimeToExcel(DateTimeInterface $dateValue)
 
     /**
      * Convert a Unix timestamp to an MS Excel serialized date/time value.
+     * The use of Unix timestamps, and therefore this function, is discouraged.
      *
      * @param int $dateValue Unix Timestamp
      *