Issue #2883892 by Jo Fitzgerald, voleger, ozin, mpdonadio, Taran2L, heddn: Add...

Issue #2883892 by Jo Fitzgerald, voleger, ozin, mpdonadio, Taran2L, heddn: Add from/to timezone settings for the "FormatDate process plugin"

core/modules/migrate/src/Plugin/migrate/process/FormatDate.php

@@ -15,10 +15,28 @@
  * - from_format: The source format string as accepted by
  *   @link http://php.net/manual/datetime.createfromformat.php \DateTime::createFromFormat. @endlink
  * - to_format: The destination format.
- * - timezone: String identifying the required time zone, see
+ * - timezone: (deprecated) String identifying the required time zone, see
+ *   DateTimePlus::__construct(). The timezone configuration key is deprecated
+ *   in Drupal 8.4.x and will be removed before Drupal 9.0.0, use from_timezone
+ *   and to_timezone instead.
+ * - from_timezone: String identifying the required source time zone, see
+ *   DateTimePlus::__construct().
+ * - to_timezone: String identifying the required destination time zone, see
  *   DateTimePlus::__construct().
  * - settings: keyed array of settings, see DateTimePlus::__construct().
  *
+ * Configuration keys from_timezone and to_timezone are both optional. Possible
+ * input variants:
+ * - Both from_timezone and to_timezone are empty. Date will not be converted
+ *   and be treated as date in default timezone.
+ * - Only from_timezone is set. Date will be converted from timezone specified
+ *   in from_timezone key to the default timezone.
+ * - Only to_timezone is set. Date will be converted from the default timezone
+ *   to the timezone specified in to_timezone key.
+ * - Both from_timezone and to_timezone are set. Date will be converted from
+ *   timezone specified in from_timezone key to the timezone specified in
+ *   to_timezone key.
+ *
  * Examples:
  *
  * Example usage for date only fields
@@ -56,7 +74,8 @@
  *     plugin: format_date
  *     from_format: 'Y-m-d\TH:i:sO'
  *     to_format: 'Y-m-d\TH:i:s'
- *     timezone: 'America/Managua'
+ *     from_timezone: 'America/Managua'
+ *     to_timezone: 'UTC'
  *     settings:
  *       validate_format: false
  *     source: event_time
@@ -94,14 +113,24 @@ public function transform($value, MigrateExecutableInterface $migrate_executable
 
     $fromFormat = $this->configuration['from_format'];
     $toFormat = $this->configuration['to_format'];
-    $timezone = isset($this->configuration['timezone']) ? $this->configuration['timezone'] : NULL;
+    if (isset($this->configuration['timezone'])) {
+      @trigger_error('Configuration key "timezone" is deprecated in 8.4.x and will be removed before Drupal 9.0.0, use "from_timezone" and "to_timezone" instead. See https://www.drupal.org/node/2885746', E_USER_DEPRECATED);
+      $from_timezone = $this->configuration['timezone'];
+      $to_timezone = isset($this->configuration['to_timezone']) ? $this->configuration['to_timezone'] : NULL;
+    }
+    else {
+      $system_timezone = date_default_timezone_get();
+      $default_timezone = !empty($system_timezone) ? $system_timezone : 'UTC';
+      $from_timezone = isset($this->configuration['from_timezone']) ? $this->configuration['from_timezone'] : $default_timezone;
+      $to_timezone = isset($this->configuration['to_timezone']) ? $this->configuration['to_timezone'] : $default_timezone;
+    }
     $settings = isset($this->configuration['settings']) ? $this->configuration['settings'] : [];
 
     // Attempts to transform the supplied date using the defined input format.
     // DateTimePlus::createFromFormat can throw exceptions, so we need to
     // explicitly check for problems.
     try {
-      $transformed = DateTimePlus::createFromFormat($fromFormat, $value, $timezone, $settings)->format($toFormat);
+      $transformed = DateTimePlus::createFromFormat($fromFormat, $value, $from_timezone, $settings)->format($toFormat, ['timezone' => $to_timezone]);
     }
     catch (\InvalidArgumentException $e) {
       throw new MigrateException(sprintf('Format date plugin could not transform "%s" using the format "%s". Error: %s', $value, $fromFormat, $e->getMessage()), $e->getCode(), $e);

core/modules/migrate/tests/src/Unit/process/FormatDateTest.php

@@ -56,6 +56,40 @@ public function testMigrateExceptionBadFormat() {
     $this->plugin->transform('January 5, 1955', $this->migrateExecutable, $this->row, 'field_date');
   }
 
+  /**
+   * Tests that "timezone" configuration key triggers deprecation error.
+   *
+   * @covers ::transform
+   *
+   * @dataProvider providerTestDeprecatedTimezoneConfigurationKey
+   *
+   * @group legacy
+   * @expectedDeprecation Configuration key "timezone" is deprecated in 8.4.x and will be removed before Drupal 9.0.0, use "from_timezone" and "to_timezone" instead. See https://www.drupal.org/node/2885746
+   */
+  public function testDeprecatedTimezoneConfigurationKey($configuration, $value, $expected) {
+    $this->plugin = new FormatDate($configuration, 'test_format_date', []);
+    $actual = $this->plugin->transform($value, $this->migrateExecutable, $this->row, 'field_date');
+
+    $this->assertEquals($expected, $actual);
+  }
+
+  /**
+   * Data provider for testDeprecatedTimezoneConfigurationKey.
+   */
+  public function providerTestDeprecatedTimezoneConfigurationKey() {
+    return [
+      [
+        'configuration' => [
+          'from_format' => 'Y-m-d\TH:i:sO',
+          'to_format' => 'c e',
+          'timezone' => 'America/Managua',
+        ],
+        'value' => '2004-12-19T10:19:42-0600',
+        'expected' => '2004-12-19T10:19:42-06:00 -06:00'
+      ],
+    ];
+  }
+
   /**
    * Tests transformation.
    *
@@ -96,10 +130,10 @@ public function datesDataProvider() {
       'datetime_datetime' => [
         'configuration' => [
           'from_format' => 'm/d/Y H:i:s',
-          'to_format' => 'Y-m-d\TH:i:s',
+          'to_format' => 'Y-m-d\TH:i:s e',
         ],
         'value' => '01/05/1955 10:43:22',
-        'expected' => '1955-01-05T10:43:22',
+        'expected' => '1955-01-05T10:43:22 Australia/Sydney',
       ],
       'empty_values' => [
         'configuration' => [
@@ -109,14 +143,37 @@ public function datesDataProvider() {
         'value' => '',
         'expected' => '',
       ],
-      'timezone' => [
+      'timezone_from_to' => [
         'configuration' => [
-          'from_format' => 'Y-m-d\TH:i:sO',
-          'to_format' => 'Y-m-d\TH:i:s',
-          'timezone' => 'America/Managua',
+          'from_format' => 'Y-m-d H:i:s',
+          'to_format' => 'Y-m-d H:i:s e',
+          'from_timezone' => 'America/Managua',
+          'to_timezone' => 'UTC',
         ],
-        'value' => '2004-12-19T10:19:42-0600',
-        'expected' => '2004-12-19T10:19:42',
+        'value' => '2004-12-19 10:19:42',
+        'expected' => '2004-12-19 16:19:42 UTC',
+      ],
+      'timezone_from' => [
+        'configuration' => [
+          'from_format' => 'Y-m-d h:i:s',
+          'to_format' => 'Y-m-d h:i:s e',
+          'from_timezone' => 'America/Managua',
+        ],
+        'value' => '2004-11-19 10:25:33',
+        // Unit tests use Australia/Sydney timezone, so date value will be
+        // converted from America/Managua to Australia/Sydney timezone.
+        'expected' => '2004-11-20 03:25:33 Australia/Sydney',
+      ],
+      'timezone_to' => [
+        'configuration' => [
+          'from_format' => 'Y-m-d H:i:s',
+          'to_format' => 'Y-m-d H:i:s e',
+          'to_timezone' => 'America/Managua',
+        ],
+        'value' => '2004-12-19 10:19:42',
+        // Unit tests use Australia/Sydney timezone, so date value will be
+        // converted from Australia/Sydney to America/Managua timezone.
+        'expected' => '2004-12-18 17:19:42 America/Managua',
       ],
     ];
   }