convert date_time and local_date_time types to Unix time

Author: adriangibbons

README.md

@@ -114,18 +114,20 @@ In addition, public functions provide a short-hand way to access commonly used e
  - sport()
 
 ###Optional Parameters
-There are three optional parameters that can be passed as an associative array when the phpFITFileAnalysis object is instantiated. These are:
+There are four optional parameters that can be passed as an associative array when the phpFITFileAnalysis object is instantiated. These are:
 
  - fix_data
  - units
  - pace
+ - garmin_timestamps
 
 For example:
 ```php
 $options = [
-    'fix_data'  => ['cadence', 'distance'],
-    'units'     => 'statute',
-    'pace'      => true
+    'fix_data'          => ['cadence', 'distance'],
+    'units'             => 'statute',
+    'pace'              => true,
+    'garmin_timestamps' => true
 ];
 $pFFA = new adriangibbons\phpFITFileAnalysis('my_fit_file.fit', $options);
 ```
@@ -263,6 +265,18 @@ foreach ($pFFA->data_mesgs['record']['speed'] as $key => $value) {
 ```
 Note that if 'raw' units are requested then this parameter has no effect on the speed data, as it is left untouched from what was read-in from the file.
 
+####Timestamps
+Unix time is the number of seconds since UTC 00:00:00 Jan 01 1970, however the FIT standard specifies that fields of type date_time and local_date_time (e.g. timestamps) are unsigned long integers representing seconds since UTC 00:00 Dec 31 1989.
+
+The difference (in seconds) between FIT and Unix timestamps is 631,065,600:
+```php
+$date_FIT = new DateTime('1989-12-31 00:00:00', new DateTimeZone('UTC'));
+$date_UNIX = new DateTime('1970-01-01 00:00:00', new DateTimeZone('UTC'));
+$diff = $date_FIT->getTimestamp() - $date_UNIX->getTimestamp();
+echo 'The difference (in seconds) between FIT and Unix timestamps is '. number_format($diff);
+```
+By default, fields of type date_time and local_date_time read from FIT files will have this delta added to them so that they can be treated as Unix time. If the FIT timestamp is required, the 'garmin_timestamps' option can be set to true.
+
 ##Analysis
 The following functions return arrays of that could be used to create tables/charts:
 ```php

demo/mountain-biking.php

@@ -56,8 +56,8 @@
 
 
     // Google Time Zone API
-    $date = new DateTime('1989-12-31', new DateTimeZone('UTC'));  // FIT timestamps are seconds since UTC 00:00:00 Dec 31 1989, source FIT SDK
-    $date_s = $date->getTimestamp() + $pFFA->data_mesgs['session']['start_time'];
+    $date = new DateTime('now', new DateTimeZone('UTC'));
+    $date_s = $pFFA->data_mesgs['session']['start_time'];
 
     $url_tz = 'https://maps.googleapis.com/maps/api/timezone/json?location='.$LatLng_start.'&timestamp='.$date_s.'&key=AIzaSyDlPWKTvmHsZ-X6PGsBPAvo0nm1-WdwuYE';
 

demo/power-analysis.php

@@ -17,8 +17,8 @@
     $pFFA = new adriangibbons\phpFITFileAnalysis(__DIR__ . $file, $options);
 
     // Google Time Zone API
-    $date = new DateTime("1989-12-31", new DateTimeZone("UTC"));  // timestamp[s]: seconds since UTC 00:00:00 Dec 31 1989
-    $date_s = $date->getTimestamp() + $pFFA->data_mesgs['session']['start_time'];
+    $date = new DateTime('now', new DateTimeZone('UTC'));
+    $date_s = $pFFA->data_mesgs['session']['start_time'];
 
     $url_tz = "https://maps.googleapis.com/maps/api/timezone/json?location=".reset($pFFA->data_mesgs['record']['position_lat']).','.reset($pFFA->data_mesgs['record']['position_long'])."&timestamp=".$date_s."&key=AIzaSyDlPWKTvmHsZ-X6PGsBPAvo0nm1-WdwuYE";
 

demo/quadrant-analysis.php

@@ -17,8 +17,8 @@
     $pFFA = new adriangibbons\phpFITFileAnalysis(__DIR__ . $file, $options);
 
     // Google Time Zone API
-    $date = new DateTime("1989-12-31", new DateTimeZone("UTC"));  // timestamp[s]: seconds since UTC 00:00:00 Dec 31 1989
-    $date_s = $date->getTimestamp() + $pFFA->data_mesgs['session']['start_time'];
+    $date = new DateTime('now', new DateTimeZone('UTC'));
+    $date_s = $pFFA->data_mesgs['session']['start_time'];
 
     $url_tz = "https://maps.googleapis.com/maps/api/timezone/json?location=".reset($pFFA->data_mesgs['record']['position_lat']).','.reset($pFFA->data_mesgs['record']['position_long'])."&timestamp=".$date_s."&key=AIzaSyDlPWKTvmHsZ-X6PGsBPAvo0nm1-WdwuYE";
 
@@ -33,7 +33,7 @@
     $ftp = 329;
     $selected_cadence = 90;
 
-    $json = $pFFA->getJSON($crank_length, $ftp, $selected_cadence);
+    $json = $pFFA->getJSON($crank_length, $ftp, ['all'], $selected_cadence);
 
 } catch (Exception $e) {
     echo 'caught exception: '.$e->getMessage();

demo/swim.php

@@ -19,13 +19,12 @@
     echo 'caught exception: '.$e->getMessage();
     die();
 }
-    
-    $units = 'm';
-    $pool_length = $pFFA->data_mesgs['session']['pool_length'];
-    $total_distance = number_format(max($pFFA->data_mesgs['record']['distance']));
+$units = 'm';
+$pool_length = $pFFA->data_mesgs['session']['pool_length'];
+$total_distance = number_format($pFFA->data_mesgs['record']['distance']);
 if ($pFFA->enumData('display_measure', $pFFA->data_mesgs['session']['pool_length_unit']) == 'statute') {
     $pool_length = round($pFFA->data_mesgs['session']['pool_length'] * 1.0936133);
-    $total_distance = number_format(max($pFFA->data_mesgs['record']['distance']) * 1.0936133);
+    $total_distance = number_format($pFFA->data_mesgs['record']['distance'] * 1.0936133);
     $units = 'yd';
 }
 ?>

src/phpFITFileAnalysis.php

@@ -23,6 +23,15 @@
     define('DATA_MESSAGE', 0);
 }
 
+/*
+ * This is the number of seconds difference between FIT and Unix timestamps.
+ * FIT timestamps are seconds since UTC 00:00:00 Dec 31 1989 (source FIT SDK)
+ * Unix time is the number of seconds since UTC 00:00:00 Jan 01 1970
+ */
+if (!defined('FIT_UNIX_TS_DIFF')) {
+    define('FIT_UNIX_TS_DIFF', 631065600);
+}
+
 class phpFITFileAnalysis
 {
     public $data_mesgs = [];  // Used to store the data read from the file in associative arrays.
@@ -35,6 +44,7 @@ class phpFITFileAnalysis
     private $file_header = [];               // Contains information about the FIT file such as the Protocol version, Profile version, and Data Size.
     private $php_trader_ext_loaded = false;  // Is the PHP Trader extension loaded? Use $this->sma() algorithm if not available.
     private $types = null;                   // Set by $endianness depending on architecture in Definition Message.
+    private $garmin_timestamps = false;      // By default the constant FIT_UNIX_TS_DIFF will be added to timestamps.
 
     // Enumerated data looked up by enumData().
     // Values from 'Profile.xls' contained within the FIT SDK.
@@ -856,6 +866,9 @@ public function __construct($file_path, $options = null)
             throw new \Exception('phpFITFileAnalysis->__construct(): file \''.$file_path.'\' does not exist!');
         }
         $this->options = $options;
+        if (isset($options['garmin_timestamps']) && $options['garmin_timestamps'] == true) {
+            $this->garmin_timestamps = true;
+        }
         $this->php_trader_ext_loaded = extension_loaded('trader');
 
         /**
@@ -993,6 +1006,11 @@ private function readDataRecords()
                                 // Check if it's an invalid value for the type
                                 $tmp_value = unpack($this->types[$field_defn['base_type']], substr($this->file_contents, $this->file_pointer, $field_defn['size']))['tmp'];
                                 if ($tmp_value !== $this->invalid_values[$field_defn['base_type']]) {
+                                    // If it's a timestamp, compensate between different in FIT and Unix timestamp epochs
+                                    if ($field_defn['field_definition_number'] === 253 && !$this->garmin_timestamps) {
+                                        $tmp_value += FIT_UNIX_TS_DIFF;
+                                    }
+                                    
                                     // If it's a Record data message, store all the pieces in the temporary array as the timestamp may not be first...
                                     if ($this->defn_mesgs[$local_mesg_type]['global_mesg_num'] === 20) {
                                         $tmp_record_array[$this->data_mesg_info[$this->defn_mesgs[$local_mesg_type]['global_mesg_num']]['field_defns'][$field_defn['field_definition_number']]['field_name']] = $tmp_value / $this->data_mesg_info[$this->defn_mesgs[$local_mesg_type]['global_mesg_num']]['field_defns'][$field_defn['field_definition_number']]['scale'] - $this->data_mesg_info[$this->defn_mesgs[$local_mesg_type]['global_mesg_num']]['field_defns'][$field_defn['field_definition_number']]['offset'];
@@ -1035,6 +1053,45 @@ private function readDataRecords()
      */
     private function fixData($options)
     {
+        // By default the constant FIT_UNIX_TS_DIFF will be added to timestamps, which have field type of date_time (or local_date_time).
+        // Timestamp fields (field number == 253) converted after being unpacked in $this->readDataRecords().
+        if (!$this->garmin_timestamps) {
+            $date_times = [
+                    ['message_name' => 'activity', 'field_name' => 'local_timestamp'],
+                    ['message_name' => 'course_point', 'field_name' => 'timestamp'],
+                    ['message_name' => 'file_id', 'field_name' => 'time_created'],
+                    ['message_name' => 'goal', 'field_name' => 'end_date'],
+                    ['message_name' => 'goal', 'field_name' => 'start_date'],
+                    ['message_name' => 'lap', 'field_name' => 'start_time'],
+                    ['message_name' => 'length', 'field_name' => 'start_time'],
+                    ['message_name' => 'monitoring', 'field_name' => 'local_timestamp'],
+                    ['message_name' => 'monitoring_info', 'field_name' => 'local_timestamp'],
+                    ['message_name' => 'obdii_data', 'field_name' => 'start_timestamp'],
+                    ['message_name' => 'schedule', 'field_name' => 'scheduled_time'],
+                    ['message_name' => 'schedule', 'field_name' => 'time_created'],
+                    ['message_name' => 'segment_lap', 'field_name' => 'start_time'],
+                    ['message_name' => 'session', 'field_name' => 'start_time'],
+                    ['message_name' => 'timestamp_correlation', 'field_name' => 'local_timestamp'],
+                    ['message_name' => 'timestamp_correlation', 'field_name' => 'system_timestamp'],
+                    ['message_name' => 'training_file', 'field_name' => 'time_created'],
+                    ['message_name' => 'video_clip', 'field_name' => 'end_timestamp'],
+                    ['message_name' => 'video_clip', 'field_name' => 'start_timestamp']
+                ];
+            
+            foreach ($date_times as $date_time) {
+                if (isset($this->data_mesgs[$date_time['message_name']][$date_time['field_name']])) {
+                    if (is_array($this->data_mesgs[$date_time['message_name']][$date_time['field_name']])) {
+                        foreach ($this->data_mesgs[$date_time['message_name']][$date_time['field_name']] as &$element) {
+                            $element += FIT_UNIX_TS_DIFF;
+                        }
+                    } else {
+                        $this->data_mesgs[$date_time['message_name']][$date_time['field_name']] += FIT_UNIX_TS_DIFF;
+                    }
+                }
+            }
+        }
+
+        
         // Find messages that have been unpacked as unsigned integers that should be signed integers.
         // http://php.net/manual/en/function.pack.php - signed integers endianness is always machine dependent.
         // 131    s    signed short (always 16 bit, machine byte order)