Carbon Doctrine Types Laravel Package

Getting Started

Start by installing the package via Composer: composer require carbonphp/carbon-doctrine-types. Next, register the DBAL types in your Doctrine configuration — typically in config/packages/doctrine.php (Symfony) or config/doctrine.php (plain DBAL). Use the Type::add() method to map carbon and/or carbon_immutable to their respective classes (Carbon\Doctrine\CarbonType and Carbon\Doctrine\CarbonImmutableType). Finally, update your entity properties to use Carbon/CarbonImmutable and mark them with @ORM\Column(type="carbon") (or carbon_immutable). Your first entity save/read operation should now work out of the box — verify with tinker or a quick test route.

Implementation Patterns

• Domain-driven entities: Use Carbon for mutable temporal properties (e.g., lastLoginAt) and CarbonImmutable for stability in value objects (e.g., createdAt).
• Hybrid column mapping: Map a single DB column (e.g., datetime or timestamptz) to Carbon; rely on the library to handle DB-level casts (e.g., '2024-05-01 10:00:00' ↔ Carbon).
• Framework integration: In Laravel, register types in a service provider’s boot() method (e.g., Type::add('carbon', CarbonType::class); Type::overrideType('datetime', CarbonType::class);).
• Batch migration: Replace existing datetime/datetime_immutable columns with carbon/carbon_immutable gradually — the library handles backward compatibility with existing DB values as long as formats match.
• Consistent timezone handling: Configure Doctrine’s default_timezone and ensure Carbon::setFallbackLocale() is used in CLI/web contexts to prevent drift across environments.

Gotchas and Tips

• Platform quirks: MySQL stores timezone-agnostic datetimes by default; PostgreSQL supports timestamptz. Use CarbonImmutable + setTimezone() only at presentation layer — avoid storing raw timezones unless denormalized.
• Null safety: The types do not auto-wrap null; ensure your DB column allows NULL and type-hint properties accordingly (?Carbon, Carbon|null).
• Custom casting: Avoid mixing carbon with Doctrine’s @CustomOverride — if overriding datetime, ensure no legacy fields assume DateTimeInterface.
• Testing tip: Use Carbon::setTestNow() in tests to assert predictable persistence/hydration without mocking DB time.
• Performance: No hydration overhead beyond DBAL’s native types — but avoid Carbon::parse() in setters since hydration already handles it; prefer direct assignment.
• Extension point: Need custom behavior? Extend Carbon\Doctrine\CarbonType and override convertToPHPValue() — but prefer extending via config overrides over forks.