Search icon CANCEL
Cart icon
Close icon
You have no products in your basket yet
Save more on your purchases!
Savings automatically calculated. No voucher code required
Arrow left icon
All Products
Best Sellers
New Releases
Learning Hub
Free Learning
Arrow right icon
Persistence in PHP with Doctrine ORM
Persistence in PHP with Doctrine ORM

Persistence in PHP with Doctrine ORM: This book is designed for PHP developers and architects who want to modernize their skills through better understanding of Persistence and ORM. You'll learn through explanations and code samples, all tied to the full development of a web application.

By Kevin Dunglas
€19.99 €13.98
Book Dec 2013 114 pages 1st Edition
€19.99 €13.98
Free Trial
Renews at €14.99p/m
€19.99 €13.98
Free Trial
Renews at €14.99p/m

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Table of content icon View table of contents Preview book icon Preview Book

Persistence in PHP with Doctrine ORM

Chapter 1. Getting Started with Doctrine 2

The Doctrine project is a collection of libraries providing utilities to ease data persistence in PHP applications. It makes it possible to create complex model layers in no time that will be compatible with popular DBMS, including SQLite, MySQL, and PostgreSQL. To discover and understand Doctrine, we will create a small blog from scratch throughout this book that will mainly use the following Doctrine components:

  • Common provides utilities that are not in the PHP standard library including a class autoloader, an annotations parser, collections structures, and a cache system.

  • Database Abstraction Layer (DBAL) exposes a unique interface to access popular DBMS. Its API is similar to PDO (and PDO is used when possible). The DBAL component is also able to execute the same SQL query on different DBMS by internally rewriting the query to use specific constructs and emulate missing features.

  • Object Relational Mapper (ORM) allows accessing and managing relational database tables and rows through an object-oriented API. Thanks to it, we will directly manipulate PHP objects, and it will transparently generate SQL queries to populate, persist, update, and delete them. It is built on top of DBAL and will be the main topic of this book.


For more information on PHP Data Objects and the data-access abstraction layer provided by PHP, refer to the following link:

To learn Doctrine, we will build together a tiny blog engine with advanced features such as the following:

  • Posts list, creation, editing, and deletion

  • Comments

  • Tag filtering

  • Profiles for author of posts and comments

  • Statistics

  • Data fixtures

The following is a screenshot of the blog:

In this chapter, we will learn about the following topics:

  • Understanding concepts behind Doctrine

  • Creating the project's structure

  • Installing Composer

  • Installing Doctrine ORM, DBAL, and Common through Compose

  • Bootstrapping the app

  • Using Doctrine's Entity Manager

  • Configuring Doctrine command-line tools


To follow this tutorial, we need a proper CLI installation of PHP 5.4 or superior. We will also use the curl command to download the Composer archive and the SQLite 3 client.


For further information about PHP CLI, curl, and SQLite, refer to the following links:,, and

In the examples, we will use the PHP built-in web server and SQLite as DBMS. Doctrine is a pure PHP library. It is compatible with any web server supporting PHP, but is not limited to Apache and Nginx. Of course, it can also be used in applications that are not intended to run on web servers, such as command-line tools. On the database side, SQLite, MySQL, PostgreSQL, Oracle, and Microsoft SQL Server are officially supported.

Thanks to the DBAL component, our blog should work fine with all these DBMS. It has been tested with SQLite and MySQL.

The Doctrine project also provides Object Document Mappers (ODM) for NoSQL databases including MongoDB, CouchDB, PHPCR, and OrientDB. These topics are not covered in this book.


Do not hesitate to consult the Doctrine documentation specified in the following link while reading this book:

Understanding the concepts behind Doctrine

Doctrine ORM implements Data Mapper and Unit of Work design patterns.

The Data Mapper is a layer designed to synchronize data stored in database with their related objects of the domain layer. In other words, it does the following:

  • Inserts and updates rows in the database from data held by object properties

  • Deletes rows in the database when related entities are marked for deletion

  • Hydrates in-memory objects with data retrieved from the database


For more information about the Data Mapper and Unit of Work design patterns, you can refer to the following links: and

In the Doctrine terminology, a Data Mapper is called an Entity Manager. Entities are plain old PHP objects of the domain layer.

Thanks to the Entity Manager, they don't have to be aware that they will be stored in a database. In fact, they don't need to be aware of the existence of the Entity Manager itself. This design pattern allows reusing entity classes regardless of the persistence system.

For performance and data consistency, the Entity Manager does not sync entities with the database each time they are modified. The Unit of Work design pattern is used to keep the states of objects managed by the Data Mapper. Database synchronization happens only when requested by a call to the flush() method of the Entity Manager and is done in a transaction (if something goes wrong while synchronizing entities to the database, the database will be rolled back to its state prior to the synchronization attempt).

Imagine an entity with a public $name property. Imagine the following code being executed:

  $myEntity->name = 'My name';
  $myEntity->name = 'Kévin';

Thanks to the implementation of the Unit of Work design pattern, only one SQL query similar to the following will be issued by Doctrine:

      UPDATE MyEntity SET name='Kévin' WHERE id=1312;


The query is similar because, for performance reasons, Doctrine uses prepared statements.

We will finish the theory part with a short overview of the Entity Manager methods and their related entity states.

The following is an extract of a class diagram representing an entity and its Entity Manager:

  • The find() method hydrates and returns an entity of the type passed in the first parameter having the second parameter as an identifier. Data is retrieved from the database through a SELECT query. The state of this returned entity is managed. It means that when the flush() method is called, changes made to it will be synced to the database. The find() method is a convenience method that internally uses an entity repository to retrieve data from the database and hydrate the entity. The state of the managed entities can be changed to detached by calling the detach() method. Modifications made to the detached entity will not be synced to the database (even when the flush() method is called) until its state is set back to managed with a call to the merge() method.


    The start of Chapter 3, Associations, will be dedicated to entity repositories.

  • The persist() method tells Doctrine to set the state of the entity passed in parameter as managed. This is only useful for entities that have not been synced at least one time to the database (the default state of a newly created object is new) because entities hydrated from existing data automatically have the managed state.

  • The remove() method sets the state of the passed in entity to removed. Data related to this entity will be effectively removed from the database with a DELETE SQL query the next time the flush() method is called.

  • The flush() method syncs data of entities with managed and removed states to the database. Doctrine will issue INSERT, UPDATE, and DELETE SQL queries for the sync. Before that call, all changes are only in-memory and are never synchronized to the database.


Doctrine's Entity Manager has a lot of other useful methods documented on the Doctrine website,

This is abstract for now, but we will understand better how the Entity Manager works with numerous examples throughout the book.

Creating a project structure

The following is the folder structure of our app:

  • blog/: App root created earlier

  • bin/: Specific command line tools of our blog app

  • config/: Configuration files of our app

  • data/: The SQLite database will be stored here

  • src/: All PHP classes we write will be here

  • vendor/: This is where Composer (see the following section) stores all downloaded dependencies including the source code of Doctrine

  • bin/: This is a command-line tool provided by dependencies installed with Composer

  • web/: This is the public directory that contains PHP pages and assets such as images, CSS, and JavaScript files

We must create all these directories except the vendor/ one that will be automatically generated later.

Installing Composer

As with most modern PHP libraries, Doctrine is available through Composer, a powerful dependency manager. A PEAR channel is also available.


For more information on Composer and Pear packages, please refer to the respective links as follows: and

The following steps should be performed to install Composer:

  1. The first step to install Doctrine ORM is to grab a copy of the latest Composer version.

  2. Open your preferred terminal, go to the blog/ directory (the root of our project), and type the following command to install Composer:

      curl -sS | php

    A new file called composer.phar has been downloaded in the directory. This is a self-contained archive of Composer.

  3. Now type the following command:

      php composer.phar

    If everything is OK, all available commands are listed. Your Composer installation is up and running!

Installing Doctrine

The following steps should be performed to install Doctrine:

  1. To install Doctrine, we need to create a file called composer.json in our new blog directory. It lists dependencies of our project as shown in the following code:

        "name": "myname/blog",
        "type": "project",
        "description": "My small blog to play with Doctrine",
        "require": {
            "doctrine/orm": "2.4.*"
        "autoload": {
            "psr-0": { "": "src/" }

    This standard JSON file will be parsed by Composer to download and install all dependencies specified. Once installed, Composer will load all classes of these libraries automatically.

    The name, type, and description attributes are optional but it's a good practice to always fill them. They provide general information about the project we are working on.

    The more interesting part of this composer.json file is the require field. In order to get it installed by Composer, all libraries used by our app must be listed here. A lot of PHP libraries are available on Packagist, the default Composer package repository. Of course, it's the case of Doctrine projects.


    For more information on Packagist, go through the following link:

    We indicate that we need the latest minor release of the 2.4 branch of Doctrine ORM. You can set a major or minor version here, and even more complicated things.


    For more information on a package version, you can refer to the following link:

    The autoload field is here to tell Composer to automatically load classes of our app. We will put our specific code in a directory called src/. Our files and classes will follow the PSR-0 namespacing and file-naming standard.


    PHP Specification Requests are attempts to improve interoperability of PHP applications and libraries. They are available at

  2. It's time to use Composer to install the ORM. Run the following command:

        php composer.phar install

    New files appear in the vendor/ directory. Doctrine ORM has been installed, and Composer was smart enough to get all its dependencies, including Doctrine DBAL and Doctrine Common.

    A composer.lock file has also been created. It contains exact versions of installed libraries. This is useful for deploying applications. Thanks to this file, when running the install command, Composer will be able to retrieve the same versions that have been used in the development.

    Doctrine is now properly installed. Easy, isn't it?

  3. To update libraries when there are new releases in the 2.4 branch, we just need to type the following command:

        php composer.phar update

Bootstrapping the app

The following steps need to be performed for bootstrapping the app:

  1. Create a new file called config/config.php that will contain configuration parameters of our app as shown in the following code:

      // App configuration
      $dbParams = [
        'driver' => 'pdo_sqlite',
        'path' => __DIR__.'/../data/blog.db'
      // Dev mode?
      $dev = true;

    The Doctrine configuration parameters are stored in the $dbParams array. We will use a SQLite Database called blog.db stored in the data/ directory. If you want to use MySQL or any other DBMS, it's here that you will configure the driver to use, the database name, and the access credentials.


    The following is a sample configuration to use MySQL instead of SQLite:

    $dbParams = [
        'driver' => 'pdo_mysql',
        'host' => '',
        'dbname' => 'blog',
        'user' => 'root',
        'password' => ''

    Config keys are self-explanatory.

    If the $dev variable is true, some optimizations will be disabled to ease debugging. Disabling the dev mode allows Doctrine to put a lot of data such as metadata in powerful caches to increase overall performances of the app.


    It requires cache driver installation and extra configuration, which is available at

  2. Next, we need a way to bootstrap our app. Create a file called bootstrap.php in the src/ directory. This file will load everything we need as given in the following code:

      require_once __DIR__.'/../vendor/autoload.php';
      require_once __DIR__.'/../config/config.php';

    The first line requires the Composer autoloader. It allows you to automatically load the Doctrine's classes, the project's classes (that will be in the src/ directory), and any class of a library installed with Composer.

    The second line imports the configuration file of the app. The project structure is created and the initialization process of the app is done. We are ready to start using Doctrine.

Using Doctrine's Entity Manager

The principle of an ORM is to manage data stored in a relational database through an object-oriented API. We learned about its underlying concepts earlier in this chapter.

Each entity class is mapped to the related database table. Properties of the entity class are mapped to the table's columns.

So, the rows of a database table are represented in the PHP app by a collection of entities.

Doctrine ORM is able to retrieve data from the database and to populate entities with them. This process is called hydration.


Instead of entities, Doctrine can populate PHP arrays in different manners (with the object graph, with a rectangular result set, and so on). It is also possible to create custom hydrators by referring to the following link:

As we have learned with the Data Mapper design pattern, it also does the inverse job: it persists data held by entities to database.

We will play a lot with entities later.

Doctrine comes with the following files to map entities to tables:

  • Annotations in comment blocks that embed directly in the entities

  • XML configuration files

  • YAML configuration files

  • Plain PHP files

Annotations are fairly recent in the PHP world (they are popular in Java) but they are already widely used by Doctrine and Symfony communities. The advantages of this method are great readability and maintenance facility because mapping information is next to the PHP code. Putting mapping information directly in the code can also be a drawback in some contexts, especially for big projects that use several persistence systems.

We will use the annotation method in this book, but other methods are described in the Doctrine documentation. We will return to them in Chapter 2, Entities and Mapping Information.

In the next chapter, Chapter 2, Entities and Mapping Information, we will discover that Doctrine is smart enough to use mapping information to automatically create the related database schema.

For now, we will focus on retrieving an Entity Manager. As entities are retrieved, persisted, updated, and removed through it, this is the entry point of Doctrine ORM.

Edit the src/bootstrap.php file to retrieve a Doctrine's Entity Manager. Add the following code at the end of this file:

  $entitiesPath = array(__DIR__.'/Blog/Entity');
  $config = Setup::createAnnotationMetadataConfiguration    ($entitiesPath, $dev);
  $entityManager = EntityManager::create($dbParams, $config);


Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at If you purchased this book elsewhere, you can visit and register to have the files e-mailed directly to you.

The $entitiesPath property contains the list of paths to directories storing entity classes. We already mentioned that our app will follow the PSR-0 namespacing convention. The \Blog folder will be the root namespace and entity classes will be in the \Blog\Entity folder.

A Doctrine configuration is created to use annotations for mapping information and to be able to locate the blog's entities that we'll create.

A new EntityManager is created and configured to use our database and Doctrine settings.

For simplicity, we create a unique Entity Manager that will be used across the application. For real-world apps, you should take a look at the Dependency Injection design pattern.


Find more on Dependency Injection pattern at the following link:

Configuring Doctrine command-line tools

The Doctrine library is bundled with some useful command line tools. They provide many helpful features, including, but not limited to the ability to create database schema from entity mappings.

Composer has installed Doctrine's command line tools in the vendor/bin/ directory. But before being able to use them, a bit of configuration must be done. Command line tools internally use an Entity Manager. We need to tell them how to retrieve it.

Here, we just need to create one more file called cli-config.php in the config/ directory as follows:


// Doctrine CLI configuration file

use Doctrine\ORM\Tools\Console\ConsoleRunner;

require_once __DIR__.'/../src/bootstrap.php';

return ConsoleRunner::createHelperSet($entityManager);

Thanks to the Doctrine's conventions, the file will be automatically detected and used by the Doctrine CLI.


Command line tools will look for a file called cli-config.php in the current directory and in the config/ directory.

This file just gets a new Entity Manager using the utility class we've created earlier and configures the Doctrine CLI to use it.

Type the following command to get a list of available Doctrine commands:

  php vendor/bin/doctrine.php


In this chapter, we discovered the fundamentals of Doctrine. We now know what entities and Entity Managers are, we have installed Doctrine with the Composer dependency manager, we created the skeleton of our blog app, and we managed to get the command line tools up and running.

In the next chapter, we will create our first entity class, discover a lot of annotations to map it to the database, generate the database schema, and start dealing with entities. By the end of the next chapter, the post system of our blog will be working!

Left arrow icon Right arrow icon

Key benefits

  • Develop a fully functional Doctrine-backed web application
  • Demonstrate aspects of Doctrine using code samples
  • Generate a database schema from your PHP classes


Doctrine 2 has become the most popular modern persistence system for PHP. It can either be used as a standalone system or can be distributed with Symfony 2, and it also integrates very well with popular frameworks. It allows you to easily retrieve PHP object graphs, provides a powerful object-oriented query language called DQL, a database schema generator tool, and supports database migration. It is efficient, abstracts popular DBMS, and supports PHP 5.3 features. Doctrine is a must-have for modern PHP applications. Persistence in PHP with Doctrine ORM is a practical, hands-on guide that describes the full creation process of a web application powered by Doctrine. Core features of the ORM are explained in depth and illustrated by useful, explicit, and reusable code samples. Persistence in PHP with Doctrine ORM explains everything you need to know to get started with Doctrine in a clear and detailed manner. From installing the ORM through Composer to mastering advanced features such as native queries, this book is a full overview of the power of Doctrine. You will also learn a bunch of mapping annotations, create associations, and generate database schemas from PHP classes. You will also see how to write data fixtures, create custom entity repositories, and issue advanced DQL queries. Finally it will teach you to play with inheritance, write native queries, and use built-in lifecycle events. If you want to use a powerful persistence system for your PHP application, Persistence in PHP with Doctrine ORM is the book you.

What you will learn

  • Install Doctrine through the Composer dependency manager
  • Configure Doctrine Command Line Tools
  • Learn to manage relations between entities with different association types
  • Create data fixtures, a custom entity repository, and native SQL queries
  • Master the query builder to generate DQL queries
  • Get started with inheritance and lifecycle events

Product Details

Country selected

Publication date : Dec 18, 2013
Length 114 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781782164104
Category :

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want

Product Details

Publication date : Dec 18, 2013
Length 114 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781782164104
Category :

Table of Contents

12 Chapters
Persistence in PHP with Doctrine ORM Chevron down icon Chevron up icon
Credits Chevron down icon Chevron up icon
About the Author Chevron down icon Chevron up icon
About the Reviewers Chevron down icon Chevron up icon Chevron down icon Chevron up icon
Preface Chevron down icon Chevron up icon
1. Getting Started with Doctrine 2 Chevron down icon Chevron up icon
2. Entities and Mapping Information Chevron down icon Chevron up icon
3. Associations Chevron down icon Chevron up icon
4. Building Queries Chevron down icon Chevron up icon
5. Going Further Chevron down icon Chevron up icon
Index Chevron down icon Chevron up icon

Customer reviews

Top Reviews
Rating distribution
Empty star icon Empty star icon Empty star icon Empty star icon Empty star icon 0
(0 Ratings)
5 star 0%
4 star 0%
3 star 0%
2 star 0%
1 star 0%
Top Reviews
No reviews found
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial


How do I buy and download an eBook? Chevron down icon Chevron up icon

Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.

If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.

Please Note: Packt eBooks are non-returnable and non-refundable.

Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:

  • You may make copies of your eBook for your own use onto any machine
  • You may not pass copies of the eBook on to anyone else
How can I make a purchase on your website? Chevron down icon Chevron up icon

If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:

  1. Register on our website using your email address and the password.
  2. Search for the title by name or ISBN using the search option.
  3. Select the title you want to purchase.
  4. Choose the format you wish to purchase the title in; if you order the Print Book, you get a free eBook copy of the same title. 
  5. Proceed with the checkout process (payment to be made using Credit Card, Debit Cart, or PayPal)
Where can I access support around an eBook? Chevron down icon Chevron up icon
  • If you experience a problem with using or installing Adobe Reader, the contact Adobe directly.
  • To view the errata for the book, see and view the pages for the title you have.
  • To view your account details or to download a new copy of the book go to
  • To contact us directly if a problem is not resolved, use
What eBook formats do Packt support? Chevron down icon Chevron up icon

Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.

You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.

What are the benefits of eBooks? Chevron down icon Chevron up icon
  • You can get the information you need immediately
  • You can easily take them with you on a laptop
  • You can download them an unlimited number of times
  • You can print them out
  • They are copy-paste enabled
  • They are searchable
  • There is no password protection
  • They are lower price than print
  • They save resources and space
What is an eBook? Chevron down icon Chevron up icon

Packt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.

When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.

For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.