Annotations Reference

In this chapter a reference of every PHPCR-ODM annotation is given with short explanations on their context and usage.

Note on usage

Note that the code examples are given without their namespaces, however it is normally necessary to import the annotation namespace into your class, and to prefix each annotation with the namespace as demonstrated in the following example:

<?php
namespace MyProject\Bundle\BlogBundle\Document;
use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document()
 */
class Post
{
    /**
     * @PHPCR\Id()
     */
    protected $id;

    /**
     * @PHPCR\ParentDocument()
     */
    protected $parent;

    /**
     * @PHPCR\NodeName
     */
    protected $title;
}

Document

@Document

Optional attributes:

  • nodeType: PHPCR type for this node, default nt:unstructured.
  • repositoryClass: Name of the repository to use for this document.
  • versionable: Set to true to enable versioning, implies referenceable.
  • referenceable: Set to true to allow this node to be referenced.
  • translator: Determines how translations are stored, one of attribute or child. See langauge mapping
  • mixins: Optional list of PHPCR mixins that will be added to the node on creation. Note that if this field is present, it overwrites the same field from the anchestor documents so you have to repeat mixins you want to keep if you add a mixins field.

Minimal example:

<?php
/**
 * @Document()
 */
class User
{
  // ...
}

Full example:

<?php
/**
 * @Document(
 *   repositoryClass="MyProject\UserRepository",
 *   versionable=true,
 *   referenceable=true,
 *   translator="child",
 *   mixins={"mix:created", "mix:lastModified"}
 * )
 */
class SomeDocument
{
  // ...
}

@MappedSuperclass

A mapped superclass is an abstract or concrete class that provides persistent document state and mapping information for its subclasses but which is not itself a document.

Note

Contrary to ORM, the PHPCR-ODM with its NoSQL nature can handle documents that extend each other just like any other document, so you only need mapped superclasses in special situations. See also Inheritance Mapping.

Optional attributes:

  • nodeType: PHPCR type for this node. Default nt:unstructured.
  • repositoryClass: Fully qualified name of the repository to use for documents extending this superclass.
  • translator: Determines how translations are stored, one of attribute or child. See language mapping.
<?php
/**
 * @MappedSuperclass()
 */
class MappedSuperclassBase
{
    // ... fields and methods
}

/**
 * @Document()
 */
class DocumentSubClassFoo extends MappedSuperclassBase
{
    // ... fields and methods
}

Value Fields

These mappings mark the annotated instance variable as “persistent”. They need to be specified inside the instance variables associated PHP DocBlock comment. Any value held inside these variables will be saved to and loaded from the storage layer as part of the lifecycle of the instance variables document class.

Common optional attributes:

  • property: The PHPCR property name where this field is stored. Defaults to the field name.
  • assoc: Specify that this attribute should be an associative array. The value should be a string which will be used by the PHPCR node. Set to an empty string to automatically use the name of the annotated variable appended by “Keys”.
  • multivalue: true to specify that this property should be treated as a simple array. See Mapping multivalue properties.
  • translated: true to specify that the property should be translatable, requires the translator attribute to be specified in @Document.
  • nullable: true to specifiy that this property doesn’t have a required value, used when loading a translation, to allow loading a node with a missing translated property.

Examples:

<?php

/**
 * @Property()
 */
protected $author;

/**
 * @String(translated=true)
 */
protected $title;

/**
 * @String(translated=true, nullable=true)
 */
protected $subTitle;

/**
 * @Boolean()
 */
protected $enabled;

/**
 * @String(multivalue=true)
 */
protected $keywords; // e.g. array('dog', 'cat', 'mouse')

/**
 * @Double(assoc="")
 */
protected $exchangeRates; // e.g. array('GBP' => 0.810709, 'EUR' => 1, 'USD' => 1.307460)

@Property

Base annotation for all fields. You can use this annotation with the type attribute or the specific annotations below.

Attributes:

@Binary

Sets the type of the annotated instance variable to binary.

Attributes:

@Boolean

Sets the type of the annotated instance variable to boolean.

Attributes:

@Date

Sets the type of the annotated instance variable to DateTime.

Attributes:

@Decimal

Sets the type of the annotated instance variable to decimal. The decimal field uses the BCMath library which supports numbers of any size or precision.

Attributes:

@Double

Sets the type of the annotated instance variable to double. The PHP type will be float.

Attributes:

@Long

Sets the type of the annotated instance variable to long. The PHP type will be integer.

Attributes:

@Name

The annotated instance variable must be a valid XML CNAME value and can be used to store a valid node name.

Attributes:

@Path

The annotated instance variable must be a valid PHPCR node path and can be used to store an arbitrary reference to another node.

Attributes:

@String

Sets the type of the annotated instance variable to string.

Attributes:

@Uri

The annotated instance variable will be validated as an URI.

Attributes:

Hierarchy

These mappings mark the annotated instance variables to contain instances of Documents above or below the current Document in the document hierarchy. They need to be specified inside the instance variables associated PHP DocBlock comment.

@Child

The annotated instance variable will be populated with the named document directly below the instance variables document class in the document hierarchy.

Required attributes:

  • nodeName: PHPCR Node name of the child document to map, this should be a string.

Optional attributes:

<?php
/**
 * @Child(name="Preferences")
 */
protected $preferences;

@Children

The annotated instance variable will be populated with Documents directly below the instance variables document class in the document hierarchy.

Optional attributes:

  • filter: Child name filter; only return children whose names match the given filter.
  • fetchDepth: Performance optimisation, number of levels to pre-fetch and cache, this should be an integer.
  • ignoreUntranslated: Set to false to not throw exceptions on untranslated child documents.
  • cascade: One of persist, remove, merge, detach, refresh, translation or all. See Transitive persistence / Cascade Operations
<?php
 /**
  * @Children(filter="a*", fetchDepth=3)
  */
 private $children;

@ParentDocument

Optional attributes:

The annotated instance variable will contain the nodes parent document. Assigning a different parent will result in a move operation.

<?php

/**
 * @ParentDocument
 */
private $parent;

Identification

These mappings help to manage the identification of the document class.

@Id

The annotated instance variable will be marked with the documents identifier. The ID is the full path to the document in the document hierarchy. See identifiers.

Required attributes:

  • strategy: How to generate IDs, one of NONE, REPOSITORY, ASSIGNED or PARENT, default is PARENT See generation strategies.
<?php
/**
 * @Id()
 */
protected $id; // e.g. /path/to/mydocument

@Nodename

Mark the annotated instance variable as representing the name of the node. The name of the node is the last part of the ID. Changing the marked variable will update the nodes ID.

<?php
/**
 * @Id()
 */
protected $id; // e.g. /path/to/mydocument

/**
 * @NodeName()
 */
protected $nodeName; // e.g. mydocument

@Uuid

The annotated instance variable will be populated with a UUID (Universally Unique Identifier). The UUID is immutable. For this field to be reliably populated the document should be referenceable.

<?php
/**
 * @Uuid()
 */
protected $uuid; // e.g. 508d6621-0c20-4972-bf0e-0278ccabe6e5

Lifcycle callbacks

These annotations, applied to a method, will cause the method to be called automatically by the ODM on the lifecycle event corresponding to the name of the annotation.

Note

Unlike the Doctrine ORM it is not necessary to specify a @HasLifecycleCallbacks annotation.

@PostLoad

Life cycle callback. The marked method will be called automatically on the postLoad event. See lifecycle callbacks

<?php
 /**
  * @PostLoad
  */
 public function doSomethingOnPostLoad()
 {
    // ... do something after the Document has been loaded
 }

@PostPersist

Life cycle callback. The marked method will be called automatically on the postPersist event. See lifecycle callbacks

<?php
 /**
  * @PostPersist
  */
 public function doSomethingOnPostPersist()
 {
   // ... do something after the document has been persisted
 }

@PostRemove

Life cycle callback. The marked method will be called automatically on the postRemove event. See lifecycle callbacks

<?php
 /**
  * @PostRemove
  */
 public function doSomethingOnPostRemove()
 {
   // ... do something after the document has been removed
 }

@PostUpdate

Life cycle callback. The marked method will be called automatically on the postUpdate event. See lifecycle callbacks

<?php
 /**
  * @PostUpdate
  */
 public function doSomethingOnPostUpdate()
 {
   // ... do something after the document has been updated
 }

@PrePersist

Life cycle callback. The marked method will be called automatically on the prePersist event. See lifecycle callbacks

<?php
 /**
  * @PrePersist
  */
 public function doSomethingOnPrePersist()
 {
   // ... do something before the document has been persisted
 }

@PreRemove

Life cycle callback. The marked method will be called automatically on the preRemove event. See lifecycle callbacks

<?php
 /**
  * @PreRemove
  */
 public function doSomethingOnPreRemove()
 {
   // ... do something before the document has been removed
 }

@PreUpdate

Life cycle callback. The marked method will be called automatically on the preUpdate event. See lifecycle callbacks

<?php
 /**
  * @PreUpdate
  */
 public function doSomethingOnPreUpdate()
 {
   // ... do something before the document has been updated
 }

PHPCR

@Node

The annotated instance variable will be populated with the underlying PHPCR node. See node field mapping.

References

@ReferenceMany

Optional attributes:

  • targetDocument: Specify type of target document class. Note that this is an optional parameter and by default you can associate any document.
  • strategy: One of weak, hard or path. See reference other documents.
<?php
/**
 * @ReferenceMany(targetDocument="Phonenumber", strategy="hard")
 */
 protected $phonenumbers;

@ReferenceOne

Optional attributes:

<?php
/**
 * @ReferenceOne(targetDocument="Contact", strategy="hard")
 */
 protected $contact;

@Referrers

Mark the annotated instance variable to contain a collection of the documents of the given document class which refer to this document.

Required attributes:

  • referringDocument: Full class name of referring document, the instances of which should be collected in the annotated property.
  • referencedBy: Name of the property from the referring document class which refers to this document class.

Optional attributes:

<?php
/**
 * @Referrers(referringDocument="Address", referencedBy="addressbook")
 */
protected $addresses;

@MixedReferrers

Mark the annotated instance variable to hold a collection of all documents which refer to this document, regardless of document class.

Optional attributes:

  • referenceType: One of weak or hard.
<?php
/**
 * @MixedReferrers()
 */
protected $referrers;

Translation

These annotations only apply to documents where the translator attribute is specified in @Document.

Example:

<?php
/**
 * @Document(translator="attribute")
 */
class MyDocument
{
   /**
    * @Locale
    */
   protected $locale;

   /**
    * @String(translated=true)
    */
   protected $title;
}

@Locale

Identifies the annotated instance variable as the field in which to store the documents current locale.

Versioning

These annotations only apply to documents where the versionable attribute is specified in @Document.

See versioning mappings.

Example:

<?php
/**
 * @Document(versionable="simple")
 */
class MyPersistentClass
{
    /**
     * @VersionName
     */
    private $versionName;

    /**
     * @VersionCreated
     */
    private $versionCreated;
}

@VersionCreated

The annotated instance variable will be populated with the date that the current document version was created. Applies only to documents with the versionable attribute.

@VersionName

The annotated instance variable will be populated with the name of the current version as given by PHPCR.

Fork me on GitHub