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.

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.

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.

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:

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';
  $entityManager->flush($myEntity);

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;

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:

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

The following is the folder structure of our app:

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

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

The following steps should be performed to install Composer:

The following steps should be performed to install Doctrine:

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

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.

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 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);

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.

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:

  <?php

// 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.

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!