Introduction

The Doctrine Persistence project is a set of shared interfaces and functionality that the different Doctrine object mappers share. You can use these interfaces and abstract classes to build your own mapper if you don't want to use the full data mappers provided by Doctrine.

Installation

The library can easily be installed with composer.

$ composer require doctrine/persistence

Overview

The interfaces and functionality in this project evolved from building several different implementations of Doctrine object mappers. The first implementation was the ORM then came the MongoDB ODM. A set of common interfaces were extracted from both projects and released in the Doctrine Common project. Over the years, more common functionality was extracted and eventually moved to this standalone project. After that, that project was itself split into several projects including this one.

A Doctrine object mapper looks like this when implemented.

1 final class User
{
    /** @var string */
    private $username;

    public function __construct(string $username)
    {
        $this->username = $username;
    }

    // ...
}

$objectManager = new ObjectManager();
$userRepository = $objectManager->getRepository(User::class);

$newUser = new User('jwage');

$objectManager->persist($newUser);
$objectManager->flush();

$user = $objectManager->find(User::class, 1);

$objectManager->remove($user);
$objectManager->flush();

$users = $userRepository->findAll();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

To learn more about the full interfaces and functionality continue reading!

Object Manager

The main public interface that an end user will use is the Doctrine\Persistence\ObjectManager interface.

1 namespace Doctrine\Persistence;

interface ObjectManager
{
    public function find($className, $id);
    public function persist($object);
    public function remove($object);
    public function merge($object);
    public function clear($objectName = null);
    public function detach($object);
    public function refresh($object);
    public function flush();
    public function getRepository($className);
    public function getClassMetadata($className);
    public function getMetadataFactory();
    public function initializeObject($obj);
    public function contains($object);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

ObjectRepository

The object repository is used to retrieve instances of your mapped objects from the mapper.

1 namespace Doctrine\Persistence;

interface ObjectRepository
{
    public function find($id);
    public function findAll();
    public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null);
    public function findOneBy(array $criteria);
    public function getClassName();
}
2
3
4
5
6
7
8
9
10

Mapping

In order for Doctrine to be able to persist your objects to a data store, you have to map the classes and class properties so they can be properly stored and retrieved while maintaining a consistent state.

ClassMetadata

1 namespace Doctrine\Persistence\Mapping;

interface ClassMetadata
{
    public function getName();
    public function getIdentifier();
    public function getReflectionClass();
    public function isIdentifier($fieldName);
    public function hasField($fieldName);
    public function hasAssociation($fieldName);
    public function isSingleValuedAssociation($fieldName);
    public function isCollectionValuedAssociation($fieldName);
    public function getFieldNames();
    public function getIdentifierFieldNames();
    public function getAssociationNames();
    public function getTypeOfField($fieldName);
    public function getAssociationTargetClass($assocName);
    public function isAssociationInverseSide($assocName);
    public function getAssociationMappedByTargetField($assocName);
    public function getIdentifierValues($object);
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ClassMetadataFactory

The Doctrine\Persistence\Mapping\ClassMetadataFactory class can be used to manage the instances for each of your mapped PHP classes.

1 namespace Doctrine\Persistence\Mapping;

interface ClassMetadataFactory
{
    public function getAllMetadata();
    public function getMetadataFor($className);
    public function hasMetadataFor($className);
    public function setMetadataFor($className, $class);
    public function isTransient($className);
}
2
3
4
5
6
7
8
9
10

Mapping Driver

In order to load ClassMetadata instances you can use the Doctrine\Persistence\Mapping\Driver\MappingDriver interface. This is the interface that does the core loading of mapping information from wherever they are stored. That may be in files, attributes, yaml, xml, etc.

1 namespace Doctrine\Persistence\Mapping\Driver;

use Doctrine\Persistence\Mapping\ClassMetadata;

interface MappingDriver
{
    public function loadMetadataForClass($className, ClassMetadata $metadata);
    public function getAllClassNames();
    public function isTransient($className);
}
2
3
4
5
6
7
8
9
10

The Doctrine Persistence project offers a few base implementations that make it easy to implement your own XML, Attributes or YAML drivers.

FileDriver

The file driver operates in a mode where it loads the mapping files of individual classes on demand. This requires the user to adhere to the convention of 1 mapping file per class and the file names of the mapping files must correspond to the full class name, including namespace, with the namespace delimiters '', replaced by dots '.'.

Extend the Doctrine\Persistence\Mapping\Driver\FileDriver class to implement your own file driver. Here is an example JSON file driver implementation.

1 use Doctrine\Persistence\Mapping\Driver\FileDriver;

final class JSONFileDriver extends FileDriver
{
    public function loadMetadataForClass($className, ClassMetadata $metadata)
    {
        $mappingFileData = $this->getElement($className);

        // use the array of mapping information from the file to populate the $metadata instance
    }

    protected function loadMappingFile($file)
    {
        return json_decode($file, true);
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Now you can use it like the following.

1 use Doctrine\Persistence\Mapping\Driver\DefaultFileLocator;

$fileLocator = new DefaultFileLocator('/path/to/mapping/files', 'json');

$jsonFileDriver = new JSONFileDriver($fileLocator);
2
3
4
5

Now if you have a class named App\Model\User and you can load the mapping information like this.

1 use App\Model\User;
use Doctrine\Persistence\Mapping\ClassMetadata;

$classMetadata = new ClassMetadata();

// looks for a file at /path/to/mapping/files/App.Model.User.json
$jsonFileDriver->loadMetadataForClass(User::class, $classMetadata);
2
3
4
5
6
7

AnnotationDriver

This driver requires the doctrine/annotations project and is deprecated because of that.

PHPDriver

The PHPDriver includes PHP files which just populate ClassMetadata instances with plain PHP code.

1 use Doctrine\Persistence\Mapping\Driver\PHPDriver;

$phpDriver = new PHPDriver('/path/to/mapping/files');
2
3

Now you can use it like the following:

1 use App\Model\User;
use Doctrine\Persistence\Mapping\ClassMetadata;

$classMetadata = new ClassMetadata();

// looks for a PHP file at /path/to/mapping/files/App.Model.User.php
$phpDriver->loadMetadataForClass(User::class, $classMetadata);
2
3
4
5
6
7

Inside the /path/to/mapping/files/App.Model.User.php file you can write raw PHP code to populate a ClassMetadata instance. You will have access to a variable named $metadata inside the file that you can use to populate the mapping metadata.

1 use App\Model\User;

$metadata->name = User::class;

// ...
2
3
4
5

StaticPHPDriver

The StaticPHPDriver calls a static loadMetadata() method on your model classes where you can manually populate the ClassMetadata instance.

1 $staticPHPDriver = new StaticPHPDriver('/path/to/classes');

$classMetadata = new ClassMetadata();

// looks for a PHP file at /path/to/classes/App/Model/User.php
$phpDriver->loadMetadataForClass(User::class, $classMetadata);
2
3
4
5
6

Your class in App\Model\User would look like the following.

1 namespace App\Model;

final class User
{
    // ...

    public static function loadMetadata(ClassMetadata $metadata)
    {
        // populate the $metadata instance
    }
}
2
3
4
5
6
7
8
9
10
11

Reflection

Doctrine uses reflection to set and get the data inside your objects. The Doctrine\Persistence\Mapping\ReflectionService is the primary interface needed for a Doctrine mapper.

1 namespace Doctrine\Persistence\Mapping;

interface ReflectionService
{
    public function getParentClasses($class);
    public function getClassShortName($class);
    public function getClassNamespace($class);
    public function getClass($class);
    public function getAccessibleProperty($class, $property);
    public function hasPublicMethod($class, $method);
}
2
3
4
5
6
7
8
9
10
11

Doctrine provides an implementation of this interface in the class named Doctrine\Persistence\Mapping\RuntimeReflectionService.

Implementations

There are several different implementations of the Doctrine Persistence APIs.

ORM - The Doctrine Object Relational Mapper is a data mapper for relational databases.
MongoDB ODM - The Doctrine MongoDB ODM is a data mapper for MongoDB.
PHPCR ODM - The Doctrine PHPCR ODM a data mapper built on top of the PHPCR API.

1	final class User { /** @var string */ private $username; public function __construct(string $username) { $this->username = $username; } // ... } $objectManager = new ObjectManager(); $userRepository = $objectManager->getRepository(User::class); $newUser = new User('jwage'); $objectManager->persist($newUser); $objectManager->flush(); $user = $objectManager->find(User::class, 1); $objectManager->remove($user); $objectManager->flush(); $users = $userRepository->findAll();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

1	namespace Doctrine\Persistence; interface ObjectManager { public function find($className, $id); public function persist($object); public function remove($object); public function merge($object); public function clear($objectName = null); public function detach($object); public function refresh($object); public function flush(); public function getRepository($className); public function getClassMetadata($className); public function getMetadataFactory(); public function initializeObject($obj); public function contains($object); }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

1	namespace Doctrine\Persistence\Mapping; interface ClassMetadata { public function getName(); public function getIdentifier(); public function getReflectionClass(); public function isIdentifier($fieldName); public function hasField($fieldName); public function hasAssociation($fieldName); public function isSingleValuedAssociation($fieldName); public function isCollectionValuedAssociation($fieldName); public function getFieldNames(); public function getIdentifierFieldNames(); public function getAssociationNames(); public function getTypeOfField($fieldName); public function getAssociationTargetClass($assocName); public function isAssociationInverseSide($assocName); public function getAssociationMappedByTargetField($assocName); public function getIdentifierValues($object); }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1	namespace Doctrine\Persistence\Mapping\Driver; use Doctrine\Persistence\Mapping\ClassMetadata; interface MappingDriver { public function loadMetadataForClass($className, ClassMetadata $metadata); public function getAllClassNames(); public function isTransient($className); }
2
3
4
5
6
7
8
9
10

1	use Doctrine\Persistence\Mapping\Driver\FileDriver; final class JSONFileDriver extends FileDriver { public function loadMetadataForClass($className, ClassMetadata $metadata) { $mappingFileData = $this->getElement($className); // use the array of mapping information from the file to populate the $metadata instance } protected function loadMappingFile($file) { return json_decode($file, true); } }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

1	use App\Model\User; use Doctrine\Persistence\Mapping\ClassMetadata; $classMetadata = new ClassMetadata(); // looks for a file at /path/to/mapping/files/App.Model.User.json $jsonFileDriver->loadMetadataForClass(User::class, $classMetadata);
2
3
4
5
6
7

1	use App\Model\User; $metadata->name = User::class; // ...
2
3
4
5

1	$staticPHPDriver = new StaticPHPDriver('/path/to/classes'); $classMetadata = new ClassMetadata(); // looks for a PHP file at /path/to/classes/App/Model/User.php $phpDriver->loadMetadataForClass(User::class, $classMetadata);
2
3
4
5
6

1	namespace App\Model; final class User { // ... public static function loadMetadata(ClassMetadata $metadata) { // populate the $metadata instance } }
2
3
4
5
6
7
8
9
10
11

Maintained

Unmaintained