Doctrine User Bundle Laravel Package

Getting Started

What this package is. tourze/doctrine-user-bundle is a Symfony bundle — not a Laravel package — that ships a reusable Doctrine ORM user model (base user entity + repository) for projects that manage identities through Doctrine rather than Eloquent. You can use it from Laravel, but you are using it as a library despite the framework, not because of it.

Minimal setup (Laravel host):

composer require tourze/doctrine-user-bundle:^1.0
composer require laravel-doctrine/orm   # if you don't already have Doctrine wired in

1. Look here first: the bundle's src/Entity/ (the abstract/base user class you extend) and src/Repository/ (the repository you get for free). Read those two before anything else — they define the contract you inherit.
2. Register the entity. Create App\Models\User (or App\Entities\User) that extends the bundle's base user class, add your own fields, and point Doctrine's mapping at your subclass, not the vendor class.
3. First real use case: authenticate against Doctrine users. Implement a Laravel UserProvider (or bind Illuminate\Contracts\Auth\UserProvider) that delegates to the bundle's user repository, then plug it into an auth guard in config/auth.php.

Also read: the bundle's DependencyInjection/ extension and any Resources/config/ service definitions. In Symfony those load automatically; in Laravel they do not, and that file tells you exactly which services and parameters you need to bind by hand.

Implementation Patterns

Extend, don't instantiate. The intended pattern is inheritance: your application user extends the provided base class, keeps its identifier/credential fields, and adds domain fields. Map with Doctrine attributes on your class; do not edit vendor mappings.

Repository as the identity boundary. Wrap the bundle's user repository behind your own class (App\Repositories\UserRepository) rather than injecting it directly into controllers. That gives you one place to change when the vendor bumps a method signature, and one place to add eager-loading or query scoping for multi-tenant setups.

Wire it as an auth provider, not a model. Laravel's Eloquent-centric Auth::attempt() won't work out of the box. Implement retrieveById, retrieveByToken, updateRememberToken, retrieveByCredentials, and validateCredentials against the Doctrine repository. Keep password hashing in Laravel's Hash facade so your validateCredentials matches the rest of the app.

Schema management. Choose one owner of the schema: either Doctrine migrations (doctrine/migrations) or Laravel migrations with raw Schema::create. Mixing the two produces drift the moment you add a field to your subclass. Whichever you pick, generate an initial migration after your subclass is finalized.

Lifecycle hooks. If the bundle exposes Doctrine event subscribers (timestamps, slug/username normalization), register them in your Doctrine manager config explicitly in Laravel — they won't self-register the way Symfony's container would.

Testing. Use an in-memory SQLite connection with doctrine/orm's schema tool to build the schema per test run. It is far faster than migrating MySQL and exercises the same mappings, so a broken attribute mapping fails in CI rather than in production.

Version pinning. Pin to ^1.0. Patch releases in this project carry no readable changelog beyond a compare link, so treat every bump as "read the diff before merging."

Gotchas and Tips

• The Symfony/Laravel seam is the whole risk. This bundle assumes a Symfony kernel: bundle class, DI extension, autoconfigured services, parameter bag. None of that exists in Laravel. Budget real time for manual service registration; check bootstrap/providers.php and a small custom service provider that binds the repository and any event subscribers.
• Inheritance mapping is where people get burned. Extending a mapped base class means deciding between mapped superclass, single-table, and joined inheritance. Get this wrong and you'll see "entity has no id" or duplicate-column errors at flush time, not at boot.
• Extending the entity invalidates vendor migrations. Any migration the bundle ships covers its table shape. Your subclass adds columns; regenerate your own migration and never run the vendor's schema assumptions blindly.
• Config quirks. Bundle config arrives as a nested array under the extension alias. In Laravel you are responsible for reading it yourself — mirror the expected keys into config/doctrine-user.php and pass them through your provider, or the bundle will silently fall back to defaults.
• Debugging order: (1) doctrine:schema:validate to confirm mappings parse, (2) dump the metadata for your subclass to confirm it inherits the parent's fields, (3) only then debug auth. Most "user isn't found" reports are metadata problems, not provider problems.
• Credential fields may not match Laravel's expectations. If the bundle's user contract exposes getters/setters that differ from Authenticatable, add an adapter rather than fighting the interface in your model.
• Extension point to prefer: a Doctrine event subscriber or a repository decorator. Avoid subclassing vendor services — those are the classes most likely to change in a 1.x patch.
• On 1.0.1 specifically: the release notes are only a 1.0.0...1.0.1 compare link, with no described changes. Diff it yourself before upgrading; a patch on a 1.0.0 launch is typically dependency-constraint or metadata fixes, but "typically" is not a changelog. If nothing in the diff touches your subclass or repository usage, upgrade and move on.