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

オブジェクト リレーショナル マッパーの核心は、すべてを結び付けるマッピング情報です。これは、さまざまなエンティティを処理するときにどのように動作するかを EntityManager に指示します。

27.1. Core Metadata Drivers

Doctrine provides a few different ways for you to specify your metadata:

Doctrine はメタデータを指定するためのいくつかの異なる方法を提供します:

• XML files (XmlDriver)

  XML ファイル (XmlDriver)

• Attributes (AttributeDriver)

  属性 (AttributeDriver)

• PHP Code in files or static functions (PhpDriver)

  ファイルまたは静的関数内の PHP コード (PhpDriver)

There are also two deprecated ways to do this:

これを行うには、非推奨の方法が 2 つあります。

• Class DocBlock Annotations (AnnotationDriver)

  クラス DocBlock 注釈 (AnnotationDriver)

• YAML files (YamlDriver)

  YAML ファイル (YamlDriver)

They will be removed in 3.0, make sure to avoid them.

これらは 3.0 で削除される予定です。使用しないようにしてください。

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.

上記のドライバーについて注意すべき重要なことは、それらが同じ最終結果への中間ステップであるということです。マッピング情報は Doctrine\ORM\Mapping\ClassMetadatainstances に入力されます。最終的に、Doctrine は ClassMetadata クラスの API を操作して、エンティティのマッピング情報を取得するだけで済みます。

Note

ノート

The populated ClassMetadata instances are also cached so in a production environment the parsing and populating only ever happens once. You can configure the metadata cache implementation using the setMetadataCacheImpl() method on the Doctrine\ORM\Configuration class:

移入された ClassMetadata インスタンスもキャッシュされるため、本番環境では解析と移入が一度だけ行われます。 Doctrine\ORM\Configuration クラスの setMetadataCacheImpl() メソッドを使用して、メタデータ キャッシュの実装を構成できます。

<?php
$em->getConfiguration()->setMetadataCacheImpl(new ApcuCache());

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:

含まれているコア メタデータ ドライバーのいずれかを使用する場合は、それを構成する必要があります。非推奨であるにも関わらず注釈ドライバーを選択した場合は、追加で doctrine/annotations をインストールする必要があります。すべてのドライバーは Doctrine\ORM\Mapping\Driver 名前空間にあります:

<?php
$driver = new \Doctrine\ORM\Mapping\Driver\XmlDriver('/path/to/mapping/files');
$em->getConfiguration()->setMetadataDriverImpl($driver);

27.2. 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:

含まれているメタデータ ドライバーに加えて、独自のドライバーを非常に簡単に実装できます。 MappingDriver インターフェイスを実装するクラスを定義するだけです。

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

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:

何らかのファイル形式から情報を解析するためのメタデータ ドライバーを作成する必要がある場合は、拡張する FileDriver 実装を提供することで、作業が少し楽になります。

<?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
    }
}

Note

ノート

When using the FileDriver it requires that you only have one entity defined per file and the file named after the class described inside where namespace separators are replaced by periods. So if you have an entity named Entities\User and you wanted to write a mapping file for your driver above you would need to name the file Entities.User.dcm.ext for it to be recognized.

FileDriver を使用する場合、ファイルごとに 1 つのエンティティのみを定義する必要があり、名前空間の区切り記号がピリオドに置き換えられている内部で記述されたクラスにちなんで名付けられたファイルが必要です。したがって、Entities\User という名前のエンティティがあり、上記のドライバのマッピング ファイルを書きたい場合は、認識されるようにファイルに Entities.User.dcm.ext という名前を付ける必要があります。

Now you can use your MyMetadataDriver implementation by setting it with the setMetadataDriverImpl() method:

これで、setMetadataDriverImpl() メソッドで設定することにより、MyMetadataDriver 実装を使用できます。

<?php
$driver = new MyMetadataDriver('/path/to/mapping/files');
$em->getConfiguration()->setMetadataDriverImpl($driver);

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

Doctrine ORM のメタデータについて知って理解する必要がある最後の部分は、ClassMetadata クラスの API です。独自のドライバーを実装するには、それらに精通している必要がありますが、必要に応じて特定のエンティティのマッピング情報を取得することがさらに重要です。

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.

ClassMetadata クラスの API の詳細については、PHP マッピングの章を参照してください。

27.4. 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:

プロジェクト内のエンティティの ClassMetadata インスタンスを取得して、マッピング情報をプログラムで使用して HTML などを生成する場合は、ClassMetadataFactory から取得できます。

<?php
$cmf = $em->getMetadataFactory();
$class = $cmf->getMetadataFor('MyEntityName');

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:

これで、エンティティについて学習し、ClassMetadata インスタンスに格納されたデータを使用して、たとえばマップされたすべてのフィールドを取得し、それらを反復処理できます。

<?php
foreach ($class->fieldMappings as $fieldMapping) {
    echo $fieldMapping['fieldName'] . "\n";
}