feat: Add support for CONVERT_TZ() function

Author: tarasom

src/Processor/Expression/FunctionEvaluator.php

@@ -99,6 +99,8 @@ public static function evaluate(
                 return self::sqlCeiling($conn, $scope, $expr, $row, $result);
             case 'FLOOR':
                 return self::sqlFloor($conn, $scope, $expr, $row, $result);
+            case 'CONVERT_TZ':
+                return self::sqlConvertTz($conn, $scope, $expr, $row, $result);
             case 'TIMESTAMPDIFF':
                 return self::sqlTimestampdiff($conn, $scope, $expr, $row, $result);
             case 'DATEDIFF':
@@ -1548,6 +1550,49 @@ private static function getPhpIntervalFromExpression(
         }
     }
 
+    /**
+     * @param FakePdoInterface $conn
+     * @param Scope $scope
+     * @param FunctionExpression $expr
+     * @param array<string, mixed> $row
+     * @param QueryResult $result
+     *
+     * @return string|null
+     * @throws ProcessorException
+     */
+    private static function sqlConvertTz(
+        FakePdoInterface $conn,
+        Scope $scope,
+        FunctionExpression $expr,
+        array $row,
+        QueryResult $result)
+    {
+        $args = $expr->args;
+
+        if (count($args) !== 3) {
+            throw new \InvalidArgumentException("CONVERT_TZ() requires exactly 3 arguments");
+        }
+
+        /** @var string|null $dtValue */
+        $dtValue = Evaluator::evaluate($conn, $scope, $args[0], $row, $result);
+        /** @var string|null $fromTzValue */
+        $fromTzValue = Evaluator::evaluate($conn, $scope, $args[1], $row, $result);
+        /** @var string|null $toTzValue */
+        $toTzValue = Evaluator::evaluate($conn, $scope, $args[2], $row, $result);
+
+        if ($dtValue === null || $fromTzValue === null || $toTzValue === null) {
+            return null;
+        }
+
+        try {
+            $dt = new \DateTime($dtValue, new \DateTimeZone($fromTzValue));
+            $dt->setTimezone(new \DateTimeZone($toTzValue));
+            return $dt->format('Y-m-d H:i:s');
+        } catch (\Exception $e) {
+            throw new \InvalidArgumentException("CONVERT_TZ() failed: " . $e->getMessage(), 0, $e);
+        }
+    }
+
     /**
      * @param FakePdoInterface $conn
      * @param Scope $scope

tests/FunctionEvaluatorTest.php

@@ -103,6 +103,59 @@ private static function getPdo(string $connection_string, bool $strict_mode = fa
         return new \Vimeo\MysqlEngine\Php7\FakePdo($connection_string, '', '', $options);
     }
 
+    /**
+     * @dataProvider convertTzProvider
+     */
+    public function testConvertTz(string $sql, ?string $expected)
+    {
+        $query = self::getConnectionToFullDB()->prepare($sql);
+        $query->execute();
+
+        $this->assertSame($expected, $query->fetch(\PDO::FETCH_COLUMN));
+    }
+
+    public function testConvertTzThrowsOnInvalidTimezone()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('CONVERT_TZ() failed: DateTimeZone::__construct(): Unknown or bad timezone (Invalid/Zone)');
+
+        $sql = "SELECT CONVERT_TZ('2025-09-23 02:30:00', 'Invalid/Zone', 'UTC');";
+        $query = self::getConnectionToFullDB()->prepare($sql);
+        $query->execute();
+    }
+
+    public function testConvertTzThrowsOnInvalidDatetime()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('CONVERT_TZ() failed: Failed to parse time string (not-a-date) at position 0 (n): The timezone could not be found in the database');
+
+        $sql = "SELECT CONVERT_TZ('not-a-date', 'UTC', 'UTC');";
+        $query = self::getConnectionToFullDB()->prepare($sql);
+        $query->execute();
+    }
+
+    private static function convertTzProvider(): array
+    {
+        return [
+            'normal conversion' => [
+                'sql' => "SELECT CONVERT_TZ('2025-09-23 02:30:00', 'UTC', 'Europe/Kyiv');",
+                'expected' => "2025-09-23 05:30:00",
+            ],
+            'same tz' => [
+                'sql' => "SELECT CONVERT_TZ('2025-12-31 23:59:59', 'Europe/Kyiv', 'Europe/Kyiv');",
+                'expected' => "2025-12-31 23:59:59",
+            ],
+            'crossing DST' => [
+                'sql' => "SELECT CONVERT_TZ('2025-07-01 12:00:00', 'America/New_York', 'UTC');",
+                'expected' => "2025-07-01 16:00:00",
+            ],
+            'null date' => [
+                'sql' => "SELECT CONVERT_TZ(NULL, 'UTC', 'Europe/Kyiv');",
+                'expected' => null,
+            ]
+        ];
+    }
+
     private static function getConnectionToFullDB(bool $emulate_prepares = true, bool $strict_mode = false) : \PDO
     {
         $pdo = self::getPdo('mysql:foo;dbname=test;', $strict_mode);