Doctrine Datetime Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — so a Laravel developer will only touch it inside a Symfony/Doctrine codebase (or a Laravel app using doctrine/dbal directly with a Symfony-style kernel). Treat it as a Doctrine DBAL type extension for PostgreSQL.

Minimal steps:

1. Require it:

   composer require sprintf/doctrine-datetime-bundle
   

2. Register the bundle in config/bundles.php:

   return [
       Sprintf\DoctrineDatetimeBundle\SprintfDoctrineDatetimeBundle::class => ['all' => true],
   ];
   

3. Confirm Doctrine has picked up the DBAL types. In a Symfony Flex app the bundle's compiler pass registers them; otherwise add them explicitly in config/packages/doctrine.yaml:

   doctrine:
     dbal:
       types:
         daterange: Sprintf\DoctrineDatetimeBundle\DBAL\Types\DateRangeType
         datetime:  Sprintf\DoctrineDatetimeBundle\DBAL\Types\DateTimeType
   

4. First use case — map a Postgres daterange column on an entity:

   #[ORM\Column(type: 'daterange')]
   private $availability;
   

Where to look first: the repository is tiny and effectively undocumented. Read src/DBAL/Types/ directly — the type classes are short and the only reliable source of truth for the value objects they return (if any) and the SQL they emit via getSQLDeclaration() / convertToDatabaseValue().

Implementation Patterns

• Custom DBAL type mapping. The bundle's value is that Doctrine core doesn't ship a daterange type, so mapping Postgres range columns to PHP requires a custom type. Once registered, entity mappings, migrations and SchemaTool all work normally with type: 'daterange'.
• Migration generation. Because the type implements getSQLDeclaration(), doctrine:migrations:diff will emit DATERANGE columns correctly. Always review generated SQL — a hand-rolled type can produce a subtly wrong declaration.
• Query building. DQL has no native range operators. Use ->setParameter() with the type instance to round-trip values, and for range predicates (&&, @>, <<) drop to NativeQuery or the DBAL Connection::executeQuery(). Don't expect the bundle to add DQL functions.
• Repository pattern. Encapsulate range predicates in a repository method that assembles raw SQL fragments, keeping entity code free of Postgres-specific operators.
• Testing. For daterange you need a real Postgres instance — SQLite/MySQL won't emulate range types. Use dama/doctrine-test-bundle with a Postgres container, and assert on SELECT ... WHERE daterange @> :date style predicates to verify the type round-trips.
• Integration tip. If exposing ranges over an API (e.g. [lower, upper) semantics), convert the DBAL value to your own DTO at the repository boundary so the rest of the app isn't coupled to this bundle's return shape.

Gotchas and Tips

• Low-maintenance risk. This package has ~1 star and effectively no dependents. There is no ecosystem, no issue activity worth relying on, and no published documentation. Budget for vendoring or forking if it's business-critical; the license is MIT so forking is cheap.
• PostgreSQL-only. The type declarations are Postgres-specific (DATERANGE, TIMESTAMPTZ). On any other driver the schema tool will fail or silently degrade. Guard your test matrix accordingly.
• Type name collisions. Postgres already has date/timestamp in Doctrine. Registering a custom datetime type can clash with Doctrine's built-in datetime — override it deliberately or rename the mapping key, otherwise you'll get confusing conversion bugs.
• Timezone surprises. A datetime type that maps to TIMESTAMPTZ will apply server/session timezone conversion. Verify whether the type stores UTC, and be explicit with DateTimeImmutable in mappings. Off-by-hours bugs here are common and silent.
• Range inclusivity. Postgres ranges carry [)/(] bounds semantics that a naive PHP array/DTO won't capture. Check convertToPHPValue() for how it represents an empty or unbounded range ([2024-01-01,)) before coding against it.
• Extension points are thin. There's little to hook; if you need custom range parsing, subclass the type and register your subclass instead of patching vendor code.
• Debugging. When values come back as raw strings, the type isn't registered for that connection — re-check doctrine.yaml and that the bundle's compiler pass ran (bin/console debug:config doctrine or doctrine:dbal:debug equivalents). Clearing the container cache is often the fix after registering a type.