Use DateTimeColumn (#323)

Author: Tigrov

CHANGELOG.md

@@ -44,6 +44,7 @@
 - Enh #319: Support `boolean` type (@Tigrov)
 - Enh #318, #320: Use `DbArrayHelper::arrange()` instead of `DbArrayHelper::index()` method (@Tigrov)
 - New #316: Realize `Schema::loadResultColumn()` method (@Tigrov)
+- New #323: Use `DateTimeColumn` class for datetime column types (@Tigrov)
 
 ## 1.3.0 March 21, 2024
 

src/Column/ColumnBuilder.php

@@ -18,6 +18,36 @@ public static function boolean(): BooleanColumn
         return new BooleanColumn(ColumnType::BOOLEAN);
     }
 
+    public static function timestamp(int|null $size = 0): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::TIMESTAMP, size: $size);
+    }
+
+    public static function datetime(int|null $size = 0): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::DATETIME, size: $size);
+    }
+
+    public static function datetimeWithTimezone(int|null $size = 0): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::DATETIMETZ, size: $size);
+    }
+
+    public static function time(int|null $size = 0): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::TIME, size: $size);
+    }
+
+    public static function timeWithTimezone(int|null $size = 0): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::TIMETZ, size: $size);
+    }
+
+    public static function date(): DateTimeColumn
+    {
+        return new DateTimeColumn(ColumnType::DATE);
+    }
+
     public static function json(): JsonColumn
     {
         return new JsonColumn(ColumnType::JSON);

src/Column/ColumnDefinitionBuilder.php

@@ -117,10 +117,12 @@ protected function getDbType(ColumnInterface $column): string
                 ColumnType::TEXT => 'clob',
                 ColumnType::BINARY => 'blob',
                 ColumnType::UUID => 'raw(16)',
-                ColumnType::DATETIME => 'timestamp',
                 ColumnType::TIMESTAMP => 'timestamp',
-                ColumnType::DATE => 'date',
+                ColumnType::DATETIME => 'timestamp',
+                ColumnType::DATETIMETZ => 'timestamp' . ($size !== null ? "($size)" : '') . ' with time zone',
                 ColumnType::TIME => 'interval day(0) to second',
+                ColumnType::TIMETZ => 'interval day(0) to second',
+                ColumnType::DATE => 'date',
                 ColumnType::ARRAY, ColumnType::STRUCTURED, ColumnType::JSON =>
                     version_compare($this->queryBuilder->getServerInfo()->getVersion(), '21', '>=')
                     ? 'json'

src/Column/ColumnFactory.php

@@ -5,14 +5,19 @@
 namespace Yiisoft\Db\Oracle\Column;
 
 use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Expression\Expression;
 use Yiisoft\Db\Schema\Column\AbstractColumnFactory;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+use function date_create_immutable;
+use function preg_match;
 use function rtrim;
 use function strcasecmp;
 
 final class ColumnFactory extends AbstractColumnFactory
 {
+    private const DATETIME_REGEX = "/^(?:TIMESTAMP|DATE|INTERVAL|to_timestamp(?:_tz)?\(|to_date\(|to_dsinterval\()\s*'(?:\d )?([^']+)/";
+
     /**
      * The mapping from physical column types (keys) to abstract column types (values).
      *
@@ -39,9 +44,9 @@ final class ColumnFactory extends AbstractColumnFactory
         'binary_double' => ColumnType::DOUBLE, // 64 bit
         'float' => ColumnType::DOUBLE, // 126 bit
         'date' => ColumnType::DATE,
-        'timestamp' => ColumnType::TIMESTAMP,
-        'timestamp with time zone' => ColumnType::TIMESTAMP,
-        'timestamp with local time zone' => ColumnType::TIMESTAMP,
+        'timestamp' => ColumnType::DATETIME,
+        'timestamp with time zone' => ColumnType::DATETIMETZ,
+        'timestamp with local time zone' => ColumnType::DATETIME,
         'interval day to second' => ColumnType::STRING,
         'interval year to month' => ColumnType::STRING,
         'json' => ColumnType::JSON,
@@ -91,13 +96,29 @@ protected function getColumnClass(string $type, array $info = []): string
         return match ($type) {
             ColumnType::BINARY => BinaryColumn::class,
             ColumnType::BOOLEAN => BooleanColumn::class,
+            ColumnType::DATETIME => DateTimeColumn::class,
+            ColumnType::DATETIMETZ => DateTimeColumn::class,
+            ColumnType::TIME => DateTimeColumn::class,
+            ColumnType::TIMETZ => DateTimeColumn::class,
+            ColumnType::DATE => DateTimeColumn::class,
             ColumnType::JSON => JsonColumn::class,
             default => parent::getColumnClass($type, $info),
         };
     }
 
     protected function normalizeNotNullDefaultValue(string $defaultValue, ColumnInterface $column): mixed
     {
-        return parent::normalizeNotNullDefaultValue(rtrim($defaultValue), $column);
+        $value = parent::normalizeNotNullDefaultValue(rtrim($defaultValue), $column);
+
+        if ($column instanceof DateTimeColumn
+            && $value instanceof Expression
+            && preg_match(self::DATETIME_REGEX, (string) $value, $matches) === 1
+        ) {
+            return date_create_immutable($matches[1]) !== false
+                ? $column->phpTypecast($matches[1])
+                : new Expression($matches[1]);
+        }
+
+        return $value;
     }
 }

src/Column/DateTimeColumn.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Oracle\Column;
+
+use DateTimeImmutable;
+use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Expression\Expression;
+use Yiisoft\Db\Expression\ExpressionInterface;
+
+use function explode;
+use function is_string;
+use function str_replace;
+
+/**
+ * Represents the metadata for a datetime column.
+ *
+ * > [!WARNING]
+ * > Oracle DBMS converts `TIMESTAMP WITH LOCAL TIME ZONE` column type values from database session time zone
+ * > to the database time zone for storage, and back from the database time zone to the session time zone when retrieve
+ * > the values.
+ *
+ * `TIMESTAMP WITH LOCAL TIME ZONE` database type does not store time zone offset and require to convert datetime values
+ * to the database session time zone before insert and back to the PHP time zone after retrieve the values.
+ * This will be done in the {@see dbTypecast()} and {@see phpTypecast()} methods and guarantees that the values
+ * are stored in the database in the correct time zone.
+ *
+ * To avoid possible time zone issues with the datetime values conversion, it is recommended to set the PHP and database
+ * time zones to UTC.
+ */
+final class DateTimeColumn extends \Yiisoft\Db\Schema\Column\DateTimeColumn
+{
+    public function dbTypecast(mixed $value): string|ExpressionInterface|null
+    {
+        $value = parent::dbTypecast($value);
+
+        if (!is_string($value)) {
+            return $value;
+        }
+
+        $value = str_replace(["'", '"', "\000", "\032"], '', $value);
+
+        return match ($this->getType()) {
+            ColumnType::TIMESTAMP, ColumnType::DATETIME, ColumnType::DATETIMETZ => new Expression("TIMESTAMP '$value'"),
+            ColumnType::TIME, ColumnType::TIMETZ => new Expression(
+                "INTERVAL '$value' DAY(0) TO SECOND" . (($size = $this->getSize()) !== null ? "($size)" : '')
+            ),
+            ColumnType::DATE => new Expression("DATE '$value'"),
+            default => $value,
+        };
+    }
+
+    public function phpTypecast(mixed $value): DateTimeImmutable|null
+    {
+        if (is_string($value) && match ($this->getType()) {
+            ColumnType::TIME, ColumnType::TIMETZ => true,
+            default => false,
+        }) {
+            $value = explode(' ', $value, 2)[1] ?? $value;
+        }
+
+        return parent::phpTypecast($value);
+    }
+
+    protected function getFormat(): string
+    {
+        return $this->format ??= match ($this->getType()) {
+            ColumnType::TIME, ColumnType::TIMETZ => '0 H:i:s' . $this->getMillisecondsFormat(),
+            default => parent::getFormat(),
+        };
+    }
+
+    protected function shouldConvertTimezone(): bool
+    {
+        return $this->shouldConvertTimezone ??= !empty($this->dbTimezone) && match ($this->getType()) {
+            ColumnType::DATETIMETZ,
+            ColumnType::DATE => false,
+            default => true,
+        };
+    }
+}

src/Connection.php

@@ -5,6 +5,7 @@
 namespace Yiisoft\Db\Oracle;
 
 use Throwable;
+use Yiisoft\Db\Connection\ServerInfoInterface;
 use Yiisoft\Db\Driver\Pdo\AbstractPdoConnection;
 use Yiisoft\Db\Driver\Pdo\PdoCommandInterface;
 use Yiisoft\Db\Exception\Exception;
@@ -92,4 +93,9 @@ public function getSchema(): SchemaInterface
     {
         return $this->schema ??= new Schema($this, $this->schemaCache, strtoupper($this->driver->getUsername()));
     }
+
+    public function getServerInfo(): ServerInfoInterface
+    {
+        return $this->serverInfo ??= new ServerInfo($this);
+    }
 }

src/Driver.php

@@ -17,7 +17,21 @@ final class Driver extends AbstractPdoDriver
     public function createConnection(): PDO
     {
         $this->attributes += [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION];
-        return parent::createConnection();
+
+        $pdo = parent::createConnection();
+
+        $pdo->exec(
+            <<<SQL
+            ALTER SESSION SET
+                NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SSXFF'
+                NLS_TIMESTAMP_TZ_FORMAT = 'YYYY-MM-DD HH24:MI:SSXFFTZH:TZM'
+                NLS_TIME_FORMAT = 'HH24:MI:SSXFF'
+                NLS_TIME_TZ_FORMAT = 'HH24:MI:SSXFFTZH:TZM'
+                NLS_DATE_FORMAT = 'YYYY-MM-DD'
+            SQL
+        );
+
+        return $pdo;
     }
 
     public function getDriverName(): string

src/Schema.php

@@ -235,6 +235,10 @@ protected function loadResultColumn(array $metadata): ColumnInterface|null
             default => $columnInfo['size'] = $metadata['len'],
         };
 
+        if ($dbType === 'timestamp with local time zone') {
+            $columnInfo['dbTimezone'] = $this->db->getServerInfo()->getTimezone();
+        }
+
         $columnInfo['notNull'] = in_array('not_null', $metadata['flags'], true);
 
         /** @psalm-suppress MixedArgumentTypeCoercion */
@@ -517,7 +521,7 @@ private function loadColumn(array $info): ColumnInterface
             default => null,
         };
 
-        return $this->db->getColumnFactory()->fromDbType($dbType, [
+        $columnInfo = [
             'autoIncrement' => $info['identity_column'] === 'YES',
             'check' => $info['check'],
             'comment' => $info['column_comment'],
@@ -530,7 +534,13 @@ private function loadColumn(array $info): ColumnInterface
             'size' => $info['size'] !== null ? (int) $info['size'] : null,
             'table' => $info['table'],
             'unique' => $info['constraint_type'] === 'U',
-        ]);
+        ];
+
+        if ($dbType === 'timestamp with local time zone') {
+            $columnInfo['dbTimezone'] = $this->db->getServerInfo()->getTimezone();
+        }
+
+        return $this->db->getColumnFactory()->fromDbType($dbType, $columnInfo);
     }
 
     /**

src/ServerInfo.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Oracle;
+
+use Yiisoft\Db\Driver\Pdo\PdoServerInfo;
+
+final class ServerInfo extends PdoServerInfo
+{
+    /** @psalm-suppress PropertyNotSetInConstructor */
+    private string $timezone;
+
+    public function getTimezone(bool $refresh = false): string
+    {
+        /** @psalm-suppress TypeDoesNotContainType */
+        if (!isset($this->timezone) || $refresh) {
+            /** @var string */
+            $this->timezone = $this->db->createCommand('SELECT SESSIONTIMEZONE FROM DUAL')->queryScalar();
+        }
+
+        return $this->timezone;
+    }
+}