Weave Code
Orm Laravel Package
doctrine/orm
Doctrine ORM is an object-relational mapper for PHP 8.1+ that provides transparent persistence for PHP objects on top of the DBAL, with DQL, an object-oriented SQL dialect inspired by Hibernate's HQL.
Doctrine Object Relational Mapper (ORM)
Frequently asked questions about Orm
- Does Doctrine ORM work with Laravel out of the box, and how do I install it?
- No. doctrine/orm is framework-agnostic and ships no Laravel service provider, so you need the community bridge laravel-doctrine/orm (plus laravel-doctrine/migrations if you want Doctrine's schema tooling). Install doctrine/orm and the bridge via Composer, publish the bridge config, point it at a DBAL connection, and generate the proxy directory. The bridge supplies the EntityManager binding and Artisan commands; its release cadence is the critical compatibility path, not Doctrine core itself.
- Is Doctrine ORM a drop-in replacement for Eloquent?
- No. Eloquent is an active-record ORM where the model is both query surface and row state; Doctrine is a data mapper where entities are plain PHP objects and persistence is mediated by an EntityManager implementing a Unit of Work and Identity Map. Switching changes how you save, retrieve, and transactionally group objects, so it is a paradigm shift rather than a package swap. It fits DDD or hexagonal Laravel codebases well and fits conventional CRUD apps poorly.
- Can Doctrine ORM and Eloquent coexist in the same Laravel application?
- Technically yes, but it creates dual persistence stacks: two connection pools, two transaction coordinators, and the risk of DB::transaction() nesting around an EntityManager::flush() that holds its own transaction. The practical rule is to segregate bounded contexts and make all writes in a Doctrine-managed context go through the EntityManager only. Mixing both against the same tables is the highest-severity architectural hazard in this integration.
- What is DQL and when should I use it instead of Eloquent?
- DQL (Doctrine Query Language) is Doctrine's object-oriented query dialect, inspired by Hibernate's HQL, that queries entities and their mapped fields rather than raw tables. Use it when you want queries that stay decoupled from the database schema and can join across mapped associations without duplicating SQL. It is the natural query surface inside a Doctrine-managed bounded context; you would not use it for Eloquent models.
- Which Doctrine ORM version should I pin for a Laravel project?
- Pin the ORM major that your chosen Laravel bridge officially supports, not the newest Doctrine branch. The README lists a 4.0.x line, but laravel-doctrine/orm typically lags Doctrine core, so verify bridge compatibility before adopting ORM 4.0. Also treat any anomalous future release date in package metadata as a metadata defect and do not let it drive the version decision. Minimum PHP is 8.1, which current Laravel 10/11/12 baselines satisfy.
- Should Doctrine Migrations or Laravel Migrations own my schema?
- Pick one owner per schema. Running both Doctrine Migrations and Laravel Migrations creates two histories that will drift, and Doctrine's schema tool is opinionated enough to try to correct framework-owned tables such as jobs, cache, and sessions. A common approach is Doctrine for domain schemas and Laravel for framework tables, with clear boundaries so neither tool touches the other's tables.
- Does Doctrine ORM work under Laravel Octane and long-lived queue workers?
- It can, but the EntityManager and its Identity Map have a lifecycle that must be managed explicitly. In long-lived processes, stale entities and unbounded memory growth are real risks, so you must clear or reset the EntityManager between requests or jobs and be careful with second-level caching. Treat Identity Map lifecycle as a first-class design concern if you run under Octane.
- Why do Doctrine entities break JSON serialization in Laravel APIs?
- Entities carry proxy objects and lazy collections, so handing them straight to JsonResource or toArray() invites circular references, N+1 queries, and accidental lazy loads after serialization. A DTO or API-resource mapping layer that converts entities into plain arrays is mandatory scope, not polish. It also keeps your API contract stable as the domain model evolves.
- How do I test Doctrine ORM entities in a Laravel test suite?
- Boot a real EntityManager against an in-memory SQLite database or a dedicated test DBAL connection and let the schema tool create the schema for each test run. Test through the EntityManager (persist, flush, clear, reload) rather than touching tables directly, so you exercise Unit of Work behavior. Because the package is framework-agnostic, most Doctrine testing patterns from Symfony apply directly inside Laravel's test suite.
- What are the alternatives to Doctrine ORM for Laravel developers?
- Eloquent is the default and by far the lowest-friction option; for data-mapper-style persistence the main alternatives are Doctrine ORM via laravel-doctrine/orm, Cycle ORM, and using Doctrine DBAL directly for hand-written queries. If your codebase is conventional CRUD, Eloquent's ergonomics usually win; if you need clean domain models, mapped inheritance, embeddables, and explicit aggregate persistence, Doctrine is the strongest fit. Weigh the bridge's maintenance cadence and the dual-stack risk before choosing.
Weaver
How can I help you explore Laravel packages today?