owlcorp/doctrine-microseconds-datetime

Adds support of microseconds time formats to Doctrine ORM & Doctrine DBAL

Maintainers

Details

github.com/owlcorp/Doctrine-Microseconds-DateTime

Source

Issues

Installs: 3 797

Dependents: 0

Suggesters: 0

Security: 0

Stars: 6

Watchers: 1

Forks: 2

Open Issues: 2

v0.9.0 2023-01-10 09:25 UTC

Requires

Requires (Dev)

MIT 477966d5b834cec50513b7ebf21d70eca74f6c02

This package is auto-updated.

Last update: 2024-12-10 14:02:09 UTC

README

What is this about?

This library has no fancy logo. It also lacks all cool badges, but what it has is a simple & ready-to-use implementation of mili- and microsecond types for Doctrine ORM/DBAL.

Why?

Date and time is hard, databases are hard - a combination of the two is a nightmare. There's a 5+ years old issue describing the problem. To do it properly and across all platforms seems nearly impossible. However, it is possible to do it with a limited scope. This is why this package was created: I personally stepped into that issue many times over the years, and here came the time to stop copying & pasting the same code.

How to use?

  1. Install with composer: composer require owlcorp/doctrine-microseconds-datetime (it will work across PHP7.0-8+)
  2. Add DBAL types
  • If you're using Symfony, edit config/packages/doctrine.yaml and add: 
    doctrine:
    dbal:
        types:
            time_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\TimeMicroType
            time_immutable_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\TimeImmutableMicroType
            datetime_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\DateTimeMicroType
            datetime_immutable_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\DateTimeImmutableMicroType
            datetimetz_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\DateTimeTzMicroType
            datetimetz_immutable_micro: OwlCorp\DoctrineMicrotime\DBAL\Types\DateTimeTzImmutableMicroType
  • If you're not using Symfony check official Doctrine documentation.

  1. For ORM, you can use it like so:

    <?php declare(strict_types=1);

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class MicroEntity
{
    #[ORM\Column(type: 'time_micro')] //you can use text names
    public \DateTime $time;

    #[ORM\Column(type: TimeImmutableMicroType::NAME)] //or constants
    public \DateTimeImmutable $timeImmutable;

    /**
     * @ORM\Column(type="datetime_micro") Of course, it works with annotations too
     */
    public \DateTime $dateTime;
}

What's supported?

See table below. These are combos which I was able to test, and they should cover most of the usecases. If you know about another database engine supporting it and it can be confirmed easily issues are welcome :)

✅ = full microseconds support (.000000) | ⚠️ = miliseconds only (.000) | ❌ = not supported

Quirks

  1. SQLite does't support native TIME/DATETIME fields, but internal functions support text-based representation with milisecond precision.
  2. Older PgSQL in certain edge-cases could loose some precision, you're unlikely to hit the non-Y2K year-2000 bug.
  3. Bonus: yes, timezone support is broken in most databases. Even where supported you probably shouldn't use it.

Sources