Metadata Drivers
The heart of an object relational mapper is the mapping information that glues everything together. It instructs the EntityManager how it should behave when dealing with the different entities.
Core Metadata Drivers
Doctrine provides a few different ways for you to specify your metadata:
- XML files (XmlDriver)
- Attributes (AttributeDriver)
- PHP Code in files or static functions (PhpDriver)
There are also two deprecated ways to do this:
- Class DocBlock Annotations (AnnotationDriver)
- YAML files (YamlDriver)
They will be removed in 3.0, make sure to avoid them.
Something important to note about the above drivers is they are all
an intermediate step to the same end result. The mapping
information is populated to Doctrine\ORM\Mapping\ClassMetadata
instances. So in the end, Doctrine only ever has to work with the
API of the ClassMetadata
class to get mapping information for
an entity.
The populated
|
If you want to use one of the included core metadata drivers you need to
configure it. If you pick the annotation driver despite it being
deprecated, you will additionally need to install
doctrine/annotations
. All the drivers are in the
Doctrine\ORM\Mapping\Driver
namespace:
Implementing Metadata Drivers
In addition to the included metadata drivers you can very easily
implement your own. All you need to do is define a class which
implements the MappingDriver
interface:
1 <?php
declare(strict_types=1);
namespace Doctrine\Persistence\Mapping\Driver;
use Doctrine\Persistence\Mapping\ClassMetadata;
/**
* Contract for metadata drivers.
*/
interface MappingDriver
{
/**
* Loads the metadata for the specified class into the provided container.
*
* @psalm-param class-string<T> $className
* @psalm-param ClassMetadata<T> $metadata
*
* @return void
*
* @template T of object
*/
public function loadMetadataForClass(string $className, ClassMetadata $metadata);
/**
* Gets the names of all mapped classes known to this driver.
*
* @return array<int, string> The names of all mapped classes known to this driver.
* @psalm-return list<class-string>
*/
public function getAllClassNames();
/**
* Returns whether the class with the specified name should have its metadata loaded.
* This is only the case if it is either mapped as an Entity or a MappedSuperclass.
*
* @psalm-param class-string $className
*
* @return bool
*/
public function isTransient(string $className);
}
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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
If you want to write a metadata driver to parse information from
some file format we've made your life a little easier by providing
the FileDriver
implementation for you to extend from:
1 <?php
use Doctrine\Persistence\Mapping\ClassMetadata;
use Doctrine\Persistence\Mapping\Driver\FileDriver;
class MyMetadataDriver extends FileDriver
{
/**
* {@inheritDoc}
*/
protected $_fileExtension = '.dcm.ext';
/**
* {@inheritDoc}
*/
public function loadMetadataForClass($className, ClassMetadata $metadata)
{
$data = $this->_loadMappingFile($file);
// populate ClassMetadata instance from $data
}
/**
* {@inheritDoc}
*/
protected function _loadMappingFile($file)
{
// parse contents of $file and return php data structure
}
}
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
28
29
30
When using the |
Now you can use your MyMetadataDriver
implementation by setting
it with the setMetadataDriverImpl()
method:
ClassMetadata
The last piece you need to know and understand about metadata in
Doctrine ORM is the API of the ClassMetadata
classes. You need to
be familiar with them in order to implement your own drivers but
more importantly to retrieve mapping information for a certain
entity when needed.
You have all the methods you need to manually specify the mapping information instead of using some mapping file to populate it from.
You can read more about the API of the ClassMetadata
classes in
the PHP Mapping chapter.
Getting ClassMetadata Instances
If you want to get the ClassMetadata
instance for an entity in
your project to programmatically use some mapping information to
generate some HTML or something similar you can retrieve it through
the ClassMetadataFactory
:
Now you can learn about the entity and use the data stored in the
ClassMetadata
instance to get all mapped fields for example and
iterate over them: