Basic Mapping

Mapping Drivers

Doctrine provides several different ways for specifying object-document mapping metadata:

• Docblock Annotations
• XML
• YAML

This manual usually mentions docblock annotations in all the examples that are spread throughout all chapters, however for many examples alternative YAML and XML examples are given as well. There are dedicated reference chapters for XML and YAML mapping, respectively that explain them in more detail. There is also an Annotation reference chapter.

Introduction to Docblock Annotations

You've probably used docblock annotations in some form already, most likely to provide documentation metadata for a tool like PHPDocumentor (@author, @link, ...). Docblock annotations are a tool to embed metadata inside the documentation section which can then be processed by some tool. Doctrine generalizes the concept of docblock annotations so that they can be used for any kind of metadata and so that it is easy to define new docblock annotations. In order to allow more involved annotation values and to reduce the chances of clashes with other docblock annotations, the Doctrine docblock annotations feature an alternative syntax that is heavily inspired by the Annotation syntax introduced in Java 5.

The implementation of these enhanced docblock annotations is located in the Doctrine\Common\Annotations namespace and therefore part of the Common package. Doctrine docblock annotations support namespaces and nested annotations among other things. The Doctrine PHPCR-ODM defines its own set of docblock annotations for supplying object-document mapping metadata.

Persistent classes

In order to mark a class for object-document persistence it needs to be designated as an document. This can be done through the @Document marker annotation.

There is a couple of options you can specify for the document mapping. Some of them are explained here, the rest in the chapters on References, Multilanguage and Versioning.

Doctrine Mapping Types

A Doctrine Mapping Type defines the mapping between a PHP type and a PHPCR property type. PHPCR defines a finite set of allowed types for properties.

For example, the Doctrine Mapping Type string defines the mapping from a PHP string to a PHPCR\\PropertyType::STRING. Here is a quick overview of the built-in mapping types:

See PHPCR\\PropertyType for details about the types.

• String: Arbitrary length strings
• Binary: Binary stream using PHP streams
• Long: Integer number (alias Int for convenience), limited by PHP_MAX_INT
• Decimal: Arbitrary length number value (PHP string type for use with bcmath)
• Double: Floating point number (alias Float for convenience)
• Date: DateTime object
• Boolean: Boolean value
• Name: A valid PHPCR name
• Path: A valid PHPCR path
• Uri: A valid URI, for example a URL

Each document can have a unique identifier for referencing it. While the uuid is also exposed as a read-only string property, the proper mapping for it is mapping it as UUID. See References for more information.

Property Mapping

After a class has been marked as a document it can specify mappings for its instance fields. Properties are only simple fields that hold scalar values like strings, numbers, etc, or arrays thereof. Although references are also stored as properties in PHPCR, they have their own mappings - see the chapter Association Mapping.

To mark a property for relational persistence the @Field docblock annotation is used. This annotation requires at least 1 attribute to be set, the type. The type attribute specifies the Doctrine Mapping Type to use for the field. If the type is not specified, PHPCR-ODM will try to let the PHPCR implementation determine a suitable type.

Example:

In that example we mapped the field count to the property count using the mapping type long and the field name is mapped to the property name with the mapping type string. As you can see, by default the column names are assumed to be the same as the field names.

Identifiers

Every document has an identifier. The id in PHPCR-ODM is the PHPCR path.

While you can manually assign the id, this is not recommended. When manually assigning, you need to ensure that the parent document resulting from the assigned path exists. The recommended way is to use the @Parentdocument and @Nodename annotations to place the document in the tree. When using that strategy, you need not have a property with the @Id annotation - though you can if you want to have access to the path for something.

$doc = new Document();
$doc->setParent($dm->find(null, '/test'));
$doc->setNodename('mynode');
// document is persisted with id /test/mynode

$doc = new Document();
$doc->setId('/test/mynode');
// document is persisted with id /test/mynode

namespace Demo;

use Doctrine\ODM\PHPCR\Id\RepositoryIdInterface;
use Doctrine\ODM\PHPCR\DocumentRepository as BaseDocumentRepository;
use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document(repositoryClass="Demo\DocumentRepository")
 */
class Document
{
    /**
     * @PHPCR\Id(strategy="repository")
     */
    private $id;

    /**
     * @PHPCR\Field(type="string")
     */
    private $title;
    //...
}

class DocumentRepository extends BaseDocumentRepository implements RepositoryIdInterface
{
    /**
     * Generate a document id
     *
     * @param object $document
     * @return string
     */
    public function generateId($document, $parent = null)
    {
        return '/functional/'.$document->getTitle();
    }
}

Symfony bundle

If you are using the Symfony DoctrinePHPCRBundle, you can use the ValidPhpcrOdm validator to validate your documents.