Guide · Open source
How to use doctrine/orm: install, map objects and run DQL
Updated · written with AI from the project's own documentation and checked against our catalogue data
doctrine/orm is an open-source object-relational mapper for PHP that lets your code save and load PHP objects in a relational database. This guide explains what it does, what you need before installing it, and how its query language, DQL, fits alongside raw SQL. By the end you will know whether it suits your project and where to find the official documentation to continue.
Doctrine ORMdoctrine/orm · ★ 10.2k · MIT Install options & downloads Quick start
- 1Confirm PHP 8.1+. Check that your PHP version is 8.1 or newer, since the README sets this as the minimum.
- 2Get the repository. Run git clone https://github.com/doctrine/orm to fetch the source.
- 3Read the stable docs. Open the official documentation linked from the README for setup and mapping details.
- 4Describe your objects. Define the PHP classes you want to store, following the mapping approach in the official docs.
- 5Persist and load objects. Use the ORM to save and retrieve your objects instead of writing SQL for each operation.
- 6Write queries in DQL. Express database queries in DQL where you want them in terms of your objects.
What doctrine/orm does
Doctrine ORM is an object-relational mapper for PHP 8.1 and newer. It provides transparent persistence for PHP objects, so you can store and retrieve them in a database instead of handling every table row by hand.
It sits on top of a database abstraction layer (DBAL), which is the part that talks to the underlying database.
Check the requirements before you install
The README lists PHP 8.1 or newer as the minimum requirement. Projects on older PHP versions cannot use this library as described in the source.
doctrine/orm is a PHP library, so it is not a fit for a non-PHP stack or for simple SQL scripts.
- PHP 8.1 or newer
- Use the project's install method (the source lists package-manager as the install method)
- Relational database access through the Doctrine DBAL layer
Get the source code
The README gives a clone command for the repository. Run it in the directory where you want the project to live.
The README's documentation link points to the stable docs, which cover setup in more detail than this page.
git clone https://github.com/doctrine/ormMap your PHP objects to the database
The core idea of the library is that you describe your objects and the ORM handles storing and loading them. The README itself does not show mapping syntax, so follow the official documentation linked from the project for the exact configuration format.
Once objects are mapped, you can persist and retrieve them without writing SQL for each operation.
Query your data with DQL
Doctrine Query Language (DQL) is an object-oriented query language inspired by Hibernate's HQL. You write queries in terms of your objects instead of table and column names.
DQL is presented as an alternative to SQL, not a requirement. You can use it where it helps and keep the DBAL for other work.
- Write queries against your own object classes
- Avoid duplicating query logic across the codebase, as the README describes
What people use it for
- Storing user accounts and their related records as PHP objects in a relational database
- Running object-oriented queries over application data using DQL instead of raw SQL
- Building a PHP application on top of an existing Doctrine DBAL setup
- Giving a team that knows Hibernate a PHP tool with a similar query language
Frequently asked questions
What are the requirements for doctrine/orm?
The README lists PHP 8.1 or newer as the minimum requirement. It is a PHP library and needs a relational database accessed through the Doctrine DBAL.
Is doctrine/orm free to use?
Yes. The licence is MIT, as stated in the project's listing. Check the LICENSE file in the repository for the full terms.
What is DQL in doctrine/orm?
DQL is Doctrine Query Language, an object-oriented query language inspired by Hibernate's HQL. It lets you write queries in terms of your objects instead of raw SQL.
Can I use doctrine/orm without DBAL?
The source describes the ORM as sitting on top of the DBAL, so the DBAL is part of the design. Consult the official documentation for how the layers are configured.
What are the alternatives to doctrine/orm?
Comparable projects named in the listing include Eloquent, Hibernate, Propel and Cycle ORM. Eloquent is in the PHP ecosystem, while Hibernate is for Java.
Why won't doctrine/orm install on my PHP version?
The README sets PHP 8.1 as the minimum. If your PHP is older, upgrade PHP before installing the library.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
doctrine/orm suits PHP developers on PHP 8.1 or newer who want to work with their own objects in a relational database, especially if they know Hibernate or already use the Doctrine DBAL. If you only need simple SQL scripts, run an older PHP version, or want a finished end-user application, pick a different tool.
Install options & downloads