simpod / doctrine-utcdatetime

0.4.0 2026-09-29 09:37 UTC

Requires

• php: ^8.4
• doctrine/dbal: ^4.5

Requires (Dev)

• doctrine/coding-standard: ^14.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan: ^2.0.0
• phpstan/phpstan-phpunit: ^2.0.0
• phpstan/phpstan-strict-rules: ^2.0.0
• phpunit/phpunit: ^13.0

MIT

• Simon Podlipsky

Published on Packagist.org on 2026-09-29 09:48 UTC

README

Contains DateTime and DateTimeImmutable Doctrine DBAL types that store datetimes in UTC timezone (TIMESTAMP type in postgres).

Requires Doctrine DBAL 4.5 or newer. DBAL 4.5 provides built-in UTC types, so new applications can use those without installing this package. For applications still using this package, see Migrating to DBAL's built-in UTC types.

For more detailed explanation see Doctrine ORM docs and this comment.

For more info about usage in Doctrine ORM see Doctrine documentation. The code is mostly copied from there.

Using the UTCDateTimeType

Installation

composer require simpod/doctrine-utcdatetime

Overriding default types in Symfony

doctrine:
    dbal:
        types:
            datetime: SimPod\DoctrineUtcDateTime\UTCDateTimeType
            datetime_immutable: SimPod\DoctrineUtcDateTime\UTCDateTimeImmutableType

Migrating to DBAL's built-in UTC types

Doctrine DBAL 4.5 includes datetime_utc and datetime_utc_immutable. These types normalize values to UTC on write and interpret database values as UTC on read. To stop using this package:

1. Update to doctrine/dbal:^4.5.
2. Find fields that rely on the overrides above. Change fields mapped as datetime to datetime_utc, and fields mapped as datetime_immutable to datetime_utc_immutable. For example, change #[ORM\Column(type: 'datetime_immutable')] to #[ORM\Column(type: 'datetime_utc_immutable')]. In XML or YAML mappings, change the field's type in the same way.
3. Remove the doctrine.dbal.types overrides shown above, then remove this package with composer remove simpod/doctrine-utcdatetime.

If you copied an older version of this example, remove its datetimetz and datetimetz_immutable overrides too. They pointed to the same plain datetime classes, not to timezone-aware types. Before removing them, check any fields mapped with those names: for UTC values in timezone-less columns, remap them to datetime_utc or datetime_utc_immutable, respectively. If the columns are timezone-aware, review their stored values and connection timezone before choosing a mapping. Leaving the old names after removing the overrides selects DBAL's timezone-aware types and changes conversion behavior; changing the column type also requires a data-aware schema migration.

Fields left as datetime or datetime_immutable after removing the overrides use Doctrine's default types and no longer get automatic UTC conversion. DBAL's mutable UTC type also leaves the input DateTime unchanged, unlike this package's mutable type, which changes its timezone in place.