Doctrine Entity Checker Bundle Laravel Package

Getting Started

Start by confirming what this package actually is: tourze/doctrine-entity-checker-bundle is a Symfony bundle that validates Doctrine ORM entity mappings — not a Laravel package. Before writing any code, open composer.json ("type": "symfony-bundle"), then read src/ for the *Bundle.php class, the DependencyInjection/ extension, and any src/Command/ or src/Checker/ directory. That source is the real documentation; there is no Laravel-facing README section and no config/ to publish.

Minimal steps in a Laravel app:

1. composer require tourze/doctrine-entity-checker-bundle:^1.0 — expect nothing to happen. No service provider, no package discovery, no php artisan command.
2. You only get value if Doctrine ORM metadata exists. That means either (a) an existing doctrine/orm + laravel-doctrine/orm setup, (b) a legacy/read-model DB mapped with Doctrine, or (c) a Symfony service living in the same monorepo.
3. If you have an EntityManager, instantiate the checker classes directly and call them from your own Artisan command — do not attempt to boot the Symfony bundle.
4. If you don't have Doctrine at all, the fastest first use case is a CI audit job in the Symfony service that owns the entities, run on every PR.

A realistic first use case: a php artisan doctrine:entities:check command that walks getMetadataFactory()->getAllMetadata() and fails non-zero when the checker reports orphaned/invalid mappings — a pre-deploy gate, not a runtime dependency.

Implementation Patterns

• CI gate, not application code. Wire the checker into a pipeline step that runs before migrations/deploy. Treat a non-zero exit as a build failure. This is the lowest-friction way to use it without adopting Symfony DI.
• Artisan wrapper command. Inject Doctrine\ORM\EntityManagerInterface, iterate getAllMetadata(), and hand each ClassMetadata to the checker. Return self::FAILURE with a table of offending entities so the output is actionable in CI logs.
• Direct instantiation over container boot. The bundle's service definitions assume Symfony's container, tags, and config tree. Composing the checker objects by hand inside a Laravel service provider you write yourself is far less work than emulating bundle registration.
• Per-connection runs. If you run multiple Doctrine connections (legacy DB, reporting replica, multi-tenant), resolve a separate EntityManager per connection and run the check for each. Metadata is cached per manager and will not cross over.
• Mixed Eloquent/Doctrine repos. The highest-value scenario: Eloquent is your default, Doctrine maps a bounded set of read models or a legacy schema. The checker catches associations pointing at classes that no longer exist — exactly the drift that Eloquent-only CI never sees.
• Pre-commit / GrumPHP-style hook for the small subset of checks that are fast; keep the full sweep in CI.
• Monorepo placement. If the Symfony service already registers the bundle, prefer using it there and letting Laravel consume the same CI job, rather than duplicating the wiring.

Gotchas and Tips

• No Laravel integration whatsoever. No Illuminate\Support\ServiceProvider, no extra.laravel auto-discovery, no publishable config. composer require succeeding tells you nothing about whether it works.
• Version 1.0.1 ships an empty changelog — only a compare link. Assume a no-op patch: no bug fixes for anything filed against 1.0.0, no new API. Pin ^1.0 (or even 1.0.1 exactly) and read git diff 1.0.0 1.0.1 yourself if your install includes .git; otherwise diff the extracted src/ trees.
• Doctrine vs Eloquent mismatch. Every check is meaningless against Eloquent models. If someone adds a guard "check all models", it will either silently pass or explode on Model classes.
• ORM 3.x vs 2.x. ClassMetadata and association-mapping APIs changed between Doctrine ORM 2 and 3 (method signatures, getAssociationMapping return shapes). A bundle this small is unlikely to support both; verify against your installed doctrine/orm constraint before trusting the output.
• Attributes vs annotations. Checkers written for older Symfony stacks may assume docblock annotations and silently skip PHP 8 attribute-mapped entities. Confirm by pointing it at one deliberately broken entity and verifying it actually fails.
• Stale metadata gives false passes. Clear the metadata/query cache before running in CI ($em->getMetadataFactory() caches aggressively; second-level cache can mask changes). Dump getAllMetadata() and assert the count is what you expect.
• Silent skip on un-mapped entities. If a class isn't in the metadata factory at all, most checkers never see it. The audit is only as complete as your mapping paths — verify your mapping config covers every entity directory.
• Maintenance risk. Single-maintainer package, minimal docs, no evidence of a test suite in the release notes. Vendor the relevant checker source into your own app/Support/Doctrine/ if the checks are the only thing you need — it is likely a few hundred lines and removes an entire dependency from your composer.json.
• Extension point (Symfony only). If you do adopt the bundle in a Symfony service, register additional checkers via the bundle's checker tag/interface rather than forking. In Laravel, that extension point doesn't exist — write your own interface and adapters.
• Debugging loop. Reproduce failures outside CI first: a tinker session with app(EntityManagerInterface::class) and a single ClassMetadata object is faster than reading pipeline logs.