Doctrine Extra Bundle Laravel Package

Getting Started

Before you do anything, confirm the stack mismatch: this is a Symfony bundle (DoctrineExtraBundle::class extending Bundle, with a DependencyInjection\Extension and config tree). It does not install into a Laravel app as a package; composer require ite/doctrine-extra-bundle will only work cleanly if symfony/framework-bundle and DoctrineBundle are already resolving in your lockfile. In a vanilla Laravel/Eloquent app, don't add it.

If your app runs Doctrine via laravel-doctrine/orm, the workable path is source, not dependency:

1. Clone the repo and read the surface in this order:
   • src/DoctrineExtraBundle.php — which compiler passes and listeners get registered.
   • src/DependencyInjection/Configuration.php — the actual feature set (README is often behind).
   • src/ leaf classes — traits, DBAL Type implementations, EventSubscribers, repository helpers. These are the only portable pieces.
2. Check composer.json constraints on php, doctrine/orm, doctrine/dbal, symfony/*. If they pin DBAL 2.x or ORM 2.x and you're on DBAL 3/4, the leaf classes will not drop in without edits.
3. If a leaf class is genuinely useful (a Type, a trait, a filter), copy it into app/Doctrine/ under your own namespace and own it.

First use case: lift one repository trait or one DBAL type into your own codebase, register it through laravel-doctrine's existing extension points (custom types map in config/doctrine.php, subscribers array), and add a test. Do not wire the Symfony bundle's DI layer into Laravel — standing up a Symfony container to host a 1-star bundle is not a trade you want to defend in review.

Implementation Patterns

Pattern: extract-then-own a DBAL type. If the bundle ships a useful Type (JSON, enum, uuid, money), copy the class, adjust the convertToPHPValue / convertToDatabaseValue signatures for DBAL 3+, and register it:

// config/doctrine.php  (laravel-doctrine)
'custom_types' => [
    'money' => App\Doctrine\Types\MoneyType::class,
],

Then reference it in the entity mapping. No Symfony anything required — a DBAL Type is a plain class.

Pattern: translate Symfony bundle config to a Laravel config file. The bundle's Configuration.php tree tells you what was meant to be tunable. Re-express the subset you actually need under config/doctrine.php or a dedicated config/persistence.php, and bind it in a service provider. This is the closest you get to "using the package" without inheriting its DI.

Pattern: repository traits over Eloquent scopes or Doctrine repositories. If the bundle provides findOrFail-style helpers, applyFilters, or pagination shims, mirror them in Eloquent as local scopes (scopeActive, scopeFilter) or in Doctrine as AbstractRepository methods. Keep the API identical to the bundle's where it reads well; you'll recognize the shape later if anything upstream changes.

Pattern: metadata utility → Doctrine event subscriber. Anything in the bundle described as "metadata handling" is almost certainly an EventSubscriber on loadClassMetadata or postLoad. Register it via laravel-doctrine:

// config/doctrine.php
'managers' => [
    'default' => [
        'event_subscribers' => [App\Doctrine\Listeners\TimestampSubscriber::class],
    ],
],

Pattern: reference for review, not adoption. The strongest day-to-day use is as a reading artifact for a junior dev on the team — "here's how a Symfony dev structures Doctrine extensions; now implement the two we need in app/Doctrine." That gets the design benefit with no dependency liability.

Gotchas and Tips

• The bundle will not boot in Laravel. No Kernel, no bundle registration, no config-tree compiler. If anyone tries to make it work by wrapping it in a Laravel service provider, they're reimplementing the bundle — stop and extract instead.
• Version drift is the main functional risk. DBAL 3 → 4 and ORM 2 → 3 both changed Type and EventSubscriber signatures. An unmaintained single-author bundle is very likely pinned to old constraints; verify against your composer.lock before writing anything.
• Zero dependents, no CVE history. Treat it as untrusted code: read the whole src/ before copying a single line, log the upstream commit SHA you lifted from, and retain the license header if you vendored it.
• Do not import the bundle's namespace (Ite\DoctrineExtraBundle\...) anywhere in your app. Wrap extracted code under App\Doctrine so a future swap is a one-file change. Callers should never see Ite\.
• Configuration tree ≠ runtime behaviour. Configuration.php declares the options; the compiler passes and tagged services decide what actually runs. If a feature seems to do nothing, grep the DependencyInjection/ folder for the tag or pass that activates it.
• Cache/container quirks don't apply to Laravel, but the equivalent bite does. If you lift an EventSubscriber or Type, run php artisan config:clear and (for Doctrine cache) php artisan doctrine:clear-metadata-cache after changes. A stale metadata cache is the classic "my mapping change did nothing" failure.
• If you're actually on Symfony somewhere in the estate, the calculus flips: pin to an exact version, add to a dependency allowlist after audit, and wrap it in your own service so removal is a single file. Still don't put it on a Laravel roadmap.
• Debugging tip when copying a Type: DBAL will silently fall back to string conversion if the class isn't registered where the manager looks. Confirm registration in the custom types map and that the entity mapping uses the type name (e.g. type="money"), not the FQCN.
• Extension point to prefer: laravel-doctrine's custom_types and event_subscribers config arrays. They give you 90% of what a Symfony bundle's DI layer was doing, without importing it.