You are browsing a version that is no longer maintained.

Annotation Mapping

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:

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.
  • uniqueNodeType: If this document has a unique node type, set to true in order to support outer joins correctly. See left outer join and right outer join. To register a custom node type, use the phpcr:node-type:register console command (use help phpcr:node-type:register for the syntax; see Tools for more information). To verify that documents claiming to have unique node types are truly unique, use the doctrine:phpcr:mapping:verify-unique-node-types command.
  • repositoryClass: Name of the repository to use for this document.
  • versionable: (string) Set to simple or full to enable versioning (respectively simple or full level), false to disable versioning inheritance. Implies referenceable. Note that not every PHPCR implementation support this feature. See Versioning.
  • 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.
  • childClasses: List of valid child classes (if empty any classes are permitted).
  • isLeaf: If the document should act as a leaf (i.e. it can have no children). Mutually exclusive with childClasses.

Minimal example:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document()
 */
class User
{
    // ...
}

Full example:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document(
 *   repositoryClass="MyProject\UserRepository",
 *   versionable="full",
 *   referenceable=true,
 *   translator="child",
 *   mixins={"mix:created", "mix:lastModified"}
 *   childClasses={"App\Documents\Article", "App\Documents\Page"}
 * )
 */
class Article
{
    // ...
}

The uniqueNodeType attribute is not supported with the sqlite database.

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

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.
1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\MappedSuperclass() */ class MappedSuperclassBase { // ... fields and methods } /** * @PHPCR\Document() */ class DocumentSubClassFoo extends MappedSuperclassBase { // ... fields and methods }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Mapping Fields

You can annotate an instance variable with the @Field anotation to make it "persistent".

Until PHPCR-ODM 1.2, the recommended way to map fields with annotations was using type specific annotations like @Binary, @Boolean, @Date, @Decimal, @Double, @Float, @Int, @Long, @Name, @Path, @String and @Uri. These were deprecated in the 1.3 release in favor of the newly added @Field(type="...") annotation to fix incompatibilities with PHP 7. In 2.0, the old annotations have been removed.

@Field

Attributes:

  • property: The PHPCR property name to which 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.
  • type: Type of the field, see table below.

Types:

  • binary: Sets the type of the annotated instance variable to binary.
  • boolean: Sets the type of the annotated instance variable to boolean.
  • date: Sets the type of the annotated instance variable to DateTime.
  • 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.
  • double: Sets the type of the annotated instance variable to double. The PHP type will be float.
  • long: Sets the type of the annotated instance variable to long. The PHP type will be integer.
  • name: The annotated instance variable must be a valid XML CNAME value and can be used to store a valid node name.
  • path: The annotated instance variable must be a valid PHPCR node path and can be used to store an arbitrary reference to another node.
  • string: Sets the type of the annotated instance variable to string.
  • uri: The annotated instance variable will be validated as an URI.

Examples:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Field(type="string")
 */
protected $author;

/**
 * @PHPCR\Field(type="string", translated=true)
 */
protected $title;

/**
 * @PHPCR\Field(type="string", translated=true, nullable=true)
 */
protected $subTitle;

/**
 * @PHPCR\Field(type="boolean")
 */
protected $enabled;

/**
 * @PHPCR\Field(type="string", multivalue=true)
 */
protected $keywords; // e.g. array('dog', 'cat', 'mouse')

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

Hierarchy

These mappings mark the annotated instance variables to contain instances of Documents above or below the current Document in the document hierarchy, or information about the state of the document within the 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:

1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\Child(name="Preferences") */ protected $preferences;
2
3
4
5
6

@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
1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\Children(filter="a*", fetchDepth=3) */ private $children;
2
3
4
5
6

@Depth

The annotated instance variable will be populated with an integer value representing the depth of the document within the document hierarchy:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Depth()
 */
private $depth;

@ParentDocument

Optional attributes:

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

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\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.
1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\Id() */ protected $id; // e.g. /path/to/mydocument
2
3
4
5
6

@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:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Id()
 */
protected $id; // e.g. /path/to/mydocument

/**
 * @PHPCR\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:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\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.

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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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 for further explanations:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

 /**
  * @PHPCR\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.
1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\ReferenceMany(targetDocument="Phonenumber", strategy="hard") */ protected $phonenumbers;
2
3
4
5
6

@ReferenceOne

Optional attributes:

1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\ReferenceOne(targetDocument="Contact", strategy="hard") */ protected $contact;
2
3
4
5
6

@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:

1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\Referrers(referringDocument="Address", referencedBy="addressbook") */ protected $addresses;
2
3
4
5
6

@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.
1use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; /** * @PHPCR\MixedReferrers() */ protected $referrers;
2
3
4
5
6

Translation

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

Example:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document(translator="attribute")
 */
class MyDocument
{
   /**
    * @PHPCR\Locale
    */
   protected $locale;

   /**
    * @PHPCR\Field(type="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:

use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR;

/**
 * @PHPCR\Document(versionable="simple")
 */
class MyPersistentClass
{
    /**
     * @PHPCR\VersionName
     */
    private $versionName;

    /**
     * @PHPCR\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.