diff --git a/docs/en/cookbook/custom_documentclass_mapper.rst b/docs/en/cookbook/custom_documentclass_mapper.rst index 2e3bf1a6d..36340a4d3 100644 --- a/docs/en/cookbook/custom_documentclass_mapper.rst +++ b/docs/en/cookbook/custom_documentclass_mapper.rst @@ -19,37 +19,30 @@ An example mapper from the `symfony cmf sandbox`_ use Doctrine\ODM\PHPCR\DocumentClassMapper; use Doctrine\ODM\PHPCR\DocumentManager; + use Doctrine\ODM\PHPCR\Document\Generic; use PHPCR\NodeInterface; use PHPCR\PropertyType; class MagnoliaDocumentClassMapper extends DocumentClassMapper { - private $templateMap; - - /** - * @param array $templateMap map from mgnl:template values to document class names - */ - public function __construct($templateMap) - { - $this->templateMap = $templateMap; + public function __construct( + /** + * @var array map from mgnl:template values to document class names + */ + private array $templateMap + ) { } /** * Determine the class name from a given node * - * @param DocumentManager - * @param NodeInterface $node - * @param string $className - * - * @return string - * * @throws \RuntimeException if no class name could be determined */ - public function getClassName(DocumentManager $dm, NodeInterface $node, $className = null) + public function getClassName(DocumentManager $dm, NodeInterface $node, string $className = null): string { $className = parent::getClassName($dm, $node, $className); - if ('Doctrine\ODM\PHPCR\Document\Generic' == $className) { + if (Generic::class === $className) { if ($node->hasNode('MetaData')) { $metaData = $node->getNode('MetaData'); if ($metaData->hasProperty('mgnl:template')) { @@ -70,7 +63,7 @@ custom mapper:: /* prepare the doctrine configuration */ $config = new \Doctrine\ODM\PHPCR\Configuration(); $map = array( - 'standard-templating-kit:pages/stkSection' => 'Sandbox\MagnoliaBundle\Document\Section', + 'standard-templating-kit:pages/stkSection' => \Sandbox\MagnoliaBundle\Document\Section::class, ); $mapper = new MagnoliaDocumentClassMapper($map); $config->setDocumentClassMapper($mapper); @@ -127,6 +120,8 @@ of instantiating the default one. An example from the `symfony cmf sandbox`_ use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\DependencyInjection\Reference; + use Sandbox\MagnoliaBundle\Document\MagnoliaDocumentClassMapper; + use Sandbox\MagnoliaBundle\Document\Section; $container ->register('doctrine.odm_configuration', '%doctrine_phpcr.odm.configuration.class%') @@ -136,10 +131,10 @@ of instantiating the default one. An example from the `symfony cmf sandbox`_ ; $container ->setDefinition('sandbox_amgnolia.odm_mapper', new Definition( - 'Sandbox\MagnoliaBundle\Document\MagnoliaDocumentClassMapper', + MagnoliaDocumentClassMapper::class, array( array( - 'standard-templating-kit:pages/stkSection' => 'Sandbox\MagnoliaBundle\Document\Section', + 'standard-templating-kit:pages/stkSection' => Section::class, ), ), )); diff --git a/docs/en/cookbook/last-modified.rst b/docs/en/cookbook/last-modified.rst index dd7c91e6a..fe92794f0 100644 --- a/docs/en/cookbook/last-modified.rst +++ b/docs/en/cookbook/last-modified.rst @@ -15,34 +15,22 @@ you can get timestamps on your documents by simply adding the mixins: .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; - /** - * @PHPCR\Document( - * mixins={"mix:created", "mix:lastModified"} - * ) - */ + #[PHPCR\Document(mixins: ["mix:created", "mix:lastModified"])] class SomeDocument { - /** - * @PHPCR\Field(type="date", property="jcr:created") - */ - private $created; + #[PHPCR\Field(type: 'date', property: 'jcr:created')] + private ?\DateTimeInterface $created; - /** - * @PHPCR\Field(type="string", property="jcr:createdBy") - */ - private $createdBy; + #[PHPCR\Field(type: 'string', property: 'jcr:createdBy')] + private ?string $createdBy; - /** - * @PHPCR\Field(type="date", property="jcr:lastModified") - */ - private $lastModified; + #[PHPCR\Field(type: 'date', property: 'jcr:lastModified')] + private ?\DateTimeInterface $lastModified; - /** - * @PHPCR\Field(type="string", property="jcr:lastModifiedBy") - */ - private $lastModifiedBy; + #[PHPCR\Field(type: 'string', property: 'jcr:lastModifiedBy')] + private ?string $lastModifiedBy; } .. code-block:: xml @@ -113,18 +101,12 @@ date, write an event listener as follows and register it with the EventManager:: */ class LastModified { - /** - * @param LifecycleEventArgs $e - */ - public function prePersist(LifecycleEventArgs $e) + public function prePersist(LifecycleEventArgs $e): void { $this->updateLastModifiedProperty($e); } - /** - * @param LifecycleEventArgs $e - */ - public function preUpdate(LifecycleEventArgs $e) + public function preUpdate(LifecycleEventArgs $e): void { $this->updateLastModifiedProperty($e); } @@ -132,10 +114,8 @@ date, write an event listener as follows and register it with the EventManager:: /** * If the document has the mixin mix:lastModified then update the field * that is mapped to jcr:lastModified. - * - * @param LifecycleEventArgs $e */ - protected function updateLastModifiedProperty(LifecycleEventArgs $e) + private function updateLastModifiedProperty(LifecycleEventArgs $e): void { $document = $e->getObject(); diff --git a/docs/en/index.rst b/docs/en/index.rst index 870bfa0e1..60d8d1afb 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -37,7 +37,6 @@ Mapping Objects onto a Document Repository * **Mapping Driver References**: :doc:`PHP Attributes ` | - :doc:`Docblock Annotations (deprecated) ` | :doc:`XML ` | :doc:`YAML ` | :doc:`Metadata Drivers ` diff --git a/docs/en/reference/annotations-mapping.rst b/docs/en/reference/annotations-mapping.rst deleted file mode 100644 index 912392c09..000000000 --- a/docs/en/reference/annotations-mapping.rst +++ /dev/null @@ -1,723 +0,0 @@ -Annotation Mapping -================== - -In this chapter a reference of every PHPCR-ODM annotation is given with short -explanations on their context and usage. - -.. warning:: - - Annotations have been deprecated in favor of :doc:`Attributes` - -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 --------- - -.. _annref_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 - :ref:`left outer join <_qbref_method_querybuilder_addjoinleftouter>` and - :ref:`right outer join <_qbref_method_querybuilder_addjoinrightouter>`. - To register a custom node type, use the ``phpcr:node-type:register`` console - command (use ``help phpcr:node-type:register`` for the syntax; see :doc:`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 :doc:`Versioning `. -- **referenceable**: Set to true to allow this node to be referenced. -- **translator**: Determines how translations are stored, one of ``attribute`` - or ``child``. See :ref:`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 - { - // ... - } - -.. note:: - - The ``uniqueNodeType`` attribute is not supported with the sqlite database. - -.. _annref_mappedsuperclass: - -@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 :doc:`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 :ref:`language mapping `. - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\MappedSuperclass() - */ - class MappedSuperclassBase - { - // ... fields and methods - } - - /** - * @PHPCR\Document() - */ - class DocumentSubClassFoo extends MappedSuperclassBase - { - // ... fields and methods - } - - -Mapping Fields --------------- - -You can annotate an instance variable with the ``@Field`` anotation to make it -"persistent". - -.. note:: - - 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. - -.. _annref_field: - - -@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 :ref:`Mapping multivalue properties `. -- **translated**: ``true`` to specify that the property should be translatable, requires the - ``translator`` attribute to be specified in :ref:`@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. ['dog', 'cat', 'mouse'] - - /** - * @PHPCR\Field(type="double", assoc="") - */ - protected $exchangeRates; // e.g. ['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. - -.. _annref_child: - -@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: - -- **cascade**: |cascade_definition| See :ref:`assocmap_cascading` - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\Child(name="Preferences") - */ - protected $preferences; - -.. _annref_children: - -@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**: |cascade_definition| See :ref:`assocmap_cascading` - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\Children(filter="a*", fetchDepth=3) - */ - private $children; - -.. _annref_depth: - -@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; - -.. _annref_parentdocument: - -@ParentDocument -~~~~~~~~~~~~~~~ - -Optional attributes: - -- **cascade**: |cascade_definition| See :ref:`assocmap_cascading` - -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. - -.. _annref_id: - -@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 :ref:`identifiers `. - -Required attributes: - -- **strategy**: How to generate IDs, one of ``NONE``, ``REPOSITORY``, ``ASSIGNED`` or ``PARENT``, default - is ``PARENT`` See :ref:`generation strategies `. - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\Id() - */ - protected $id; // e.g. /path/to/mydocument - -.. _annref_nodename: - -@Nodename -~~~~~~~~~ - -Mark the annotated instance variable as representing the name of the node. The name -of the node is the last part of the :ref:`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 - -.. _annref_uuid: - -@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 :ref:`lifecycle event ` corresponding to the name -of the annotation. - -.. note:: - - Unlike the Doctrine ORM it is **not** necessary to specify a ``@HasLifecycleCallbacks`` - annotation. - -.. _annref_postload: - -@PostLoad -~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``postLoad`` -event. See :ref:`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 - } - -.. _annref_postpersist: - -@PostPersist -~~~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``postPersist`` -event. See :ref:`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 - } - -.. _annref_postremove: - -@PostRemove -~~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``postRemove`` -event. See :ref:`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 - } - -.. _annref_postupdate: - -@PostUpdate -~~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``postUpdate`` -event. See :ref:`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 - } - -.. _annref_prepersist: - -@PrePersist -~~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``prePersist`` -event. See :ref:`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 - } - -.. _annref_preremove: - -@PreRemove -~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``preRemove`` -event. See :ref:`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 - } - -.. _annref_preupdate: - -@PreUpdate -~~~~~~~~~~ - -Life cycle callback. The marked method will be called automatically on the ``preUpdate`` -event. See :ref:`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 ------ - -.. _annref_node: - -@Node -~~~~~ - -The annotated instance variable will be populated with the underlying -PHPCR node. See :ref:`node field mapping `. - -References ----------- - -.. _annref_referencemany: - -@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 :ref:`reference other documents `. - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\ReferenceMany(targetDocument="Phonenumber", strategy="hard") - */ - protected $phonenumbers; - -.. _annref_referenceone: -.. _annref_reference: - -@ReferenceOne -~~~~~~~~~~~~~ - -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 :ref:`reference other documents `. -- **cascade**: |cascade_definition| See :ref:`assocmap_cascading` - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\ReferenceOne(targetDocument="Contact", strategy="hard") - */ - protected $contact; - -.. _annref_referrers: - -@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: - -- **cascade**: |cascade_definition| See :ref:`assocmap_cascading` - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\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``. - -.. code-block:: php - - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; - - /** - * @PHPCR\MixedReferrers() - */ - protected $referrers; - -Translation ------------ - -These annotations only apply to documents where the ``translator`` attribute is -specified in :ref:`@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; - } - -.. _annref_locale: - -@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 :ref:`@Document`. - -See :ref:`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; - } - -.. _annref_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. - -.. _annref_versionname: - -@VersionName -~~~~~~~~~~~~ - -The annotated instance variable will be populated with the name -of the current version as given by PHPCR. - -.. |cascade_definition| replace:: One of ``persist``, ``remove``, ``merge``, ``detach``, ``refresh``, ``translation`` or ``all``. diff --git a/docs/en/reference/association-mapping.rst b/docs/en/reference/association-mapping.rst index 58ee3650c..5dc93fc2f 100644 --- a/docs/en/reference/association-mapping.rst +++ b/docs/en/reference/association-mapping.rst @@ -52,15 +52,16 @@ Some sample mappings: .. code-block:: php use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ChildrenCollection; #[PHPCR\ParentDocument] - private $parent; + private object $parent; #[PHPCR\Child] - private $mychild; + private object $mychild; #[PHPCR\Children(filter: 'a*', fetchDepth: 3)] - private $children; + private ChildrenCollection $children; .. code-block:: xml @@ -94,6 +95,9 @@ document is not allowed to have children (i.e. that it is a leaf node). .. code-block:: php groups = new ArrayCollection(); } - public function getGroups() + public function getGroups(): Collection { return $this->groups; } diff --git a/docs/en/reference/attributes-mapping.rst b/docs/en/reference/attributes-mapping.rst index 7f87b541f..f93640f9b 100644 --- a/docs/en/reference/attributes-mapping.rst +++ b/docs/en/reference/attributes-mapping.rst @@ -18,13 +18,13 @@ prefix each attribute with the namespace as demonstrated in the following exampl class Post { #[PHPCR\Id] - protected $id; + private string $id; #[PHPCR\ParentDocument] - protected $parent; + private object $parent; #[PHPCR\Nodename] - protected $title; + private string $title; } Document @@ -184,22 +184,22 @@ Examples:: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Field(type: 'string')] - protected $author; + private string $author; #[PHPCR\Field(type: 'string', translated: true)] - protected $title; + private string $title; #[PHPCR\Field(type: 'string', translated: true, nullable: true)] - protected $subTitle; + private ?string $subTitle; #[PHPCR\Field(type: 'boolean')] - protected $enabled; + private bool $enabled; #[PHPCR\Field(type: 'string', multivalue: true)] - protected $keywords; // e.g. ['dog', 'cat', 'mouse'] + private array $keywords; // e.g. ['dog', 'cat', 'mouse'] #[PHPCR\Field(type: 'double', assoc: '')] - protected $exchangeRates; // e.g. ['GBP' => 0.810709, 'EUR' => 1, 'USD' => 1.307460] + private array $exchangeRates; // e.g. ['GBP' => 0.810709, 'EUR' => 1, 'USD' => 1.307460] Hierarchy --------- @@ -230,7 +230,7 @@ Optional parameters: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Child(name: 'Preferences')] - protected $preferences; + private object $preferences; .. _attref_children: @@ -251,10 +251,11 @@ Optional parameters: .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ChildrenCollection; #[PHPCR\Children(filter: 'a*', fetchDepth: 3)] - private $children; + private ChildrenCollection $children; .. _attref_depth: @@ -267,7 +268,7 @@ representing the depth of the document within the document hierarchy:: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Depth] - private $depth; + private int $depth; .. _attref_parentdocument: @@ -284,7 +285,7 @@ a different parent will result in a move operation:: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\ParentDocument] - private $parent; + private object $parent; Identification -------------- @@ -310,7 +311,7 @@ Required parameters: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Id] - protected $id; // e.g. /path/to/mydocument + private string $id; // e.g. /path/to/mydocument .. _attref_nodename: @@ -324,10 +325,10 @@ the nodes ID:: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Id] - protected $id; // e.g. /path/to/mydocument + private string $id; // e.g. /path/to/mydocument #[PHPCR\Nodename] - protected $nodeName; // e.g. mydocument + private string $nodeName; // e.g. mydocument .. _attref_uuid: @@ -342,7 +343,7 @@ this field to be reliably populated the document should be use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Uuid] - protected $uuid; // e.g. 508d6621-0c20-4972-bf0e-0278ccabe6e5 + private string $uuid; // e.g. 508d6621-0c20-4972-bf0e-0278ccabe6e5 Lifcycle callbacks ------------------ @@ -367,7 +368,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PostLoad] - public function doSomethingOnPostLoad() + public function doSomethingOnPostLoad(): void { // ... do something after the Document has been loaded } @@ -383,7 +384,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PostPersist] - public function doSomethingOnPostPersist() + public function doSomethingOnPostPersist(): void { // ... do something after the document has been persisted } @@ -399,7 +400,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PostRemove] - public function doSomethingOnPostRemove() + public function doSomethingOnPostRemove(): void { // ... do something after the document has been removed } @@ -415,7 +416,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PostUpdate] - public function doSomethingOnPostUpdate() + public function doSomethingOnPostUpdate(): void { // ... do something after the document has been updated } @@ -431,7 +432,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PrePersist] - public function doSomethingOnPrePersist() + public function doSomethingOnPrePersist(): void { // ... do something before the document has been persisted } @@ -447,7 +448,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PreRemove] - public function doSomethingOnPreRemove() + public function doSomethingOnPreRemove(): void { // ... do something before the document has been removed } @@ -463,7 +464,7 @@ event. See :ref:`lifecycle callbacks ` for further ex use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PreUpdate] - public function doSomethingOnPreUpdate() + public function doSomethingOnPreUpdate(): void { // ... do something before the document has been updated } @@ -495,10 +496,11 @@ Optional parameters: .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ReferenceManyCollection; - #[PHPCR\ReferenceMany(targetDocument: PhoneNumber::class, strategy: 'hard')] - protected $phoneNumbers; + #[PHPCR\ReferenceMany(targetDocument: PhoneNumber::class, strategy: 'hard')] + private ReferenceManyCollection $phoneNumbers; .. _attref_referenceone: .. _attref_reference: @@ -518,7 +520,7 @@ Optional parameters: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\ReferenceOne(targetDocument: Contact::class, strategy: 'hard')] - protected $contact; + private object $contact; .. _attref_referrers: @@ -541,10 +543,11 @@ Optional parameters: .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ReferrersCollection; - #[PHPCR\Referrers(referringDocument: Address::class, referencedBy: 'addressbook')] - protected $addresses; + #[PHPCR\Referrers(referringDocument: Address::class, referencedBy: 'addressbook')] + private ReferrersCollection $addresses; #[MixedReferrers] ~~~~~~~~~~~~~~~~~ @@ -558,10 +561,11 @@ Optional parameters: .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ReferrersCollection; - #[PHPCR\MixedReferrers] - protected $referrers; + #[PHPCR\MixedReferrers] + private ReferrersCollection $referrers; Translation ----------- @@ -577,10 +581,10 @@ Example:: class MyDocument { #[PHPCR\Locale] - protected $locale; + private string $locale; #[PHPCR\Field(type: 'string', translated: true)] - protected $title; + private string $title; } .. _attref_locale: @@ -607,10 +611,10 @@ Example:: class MyPersistentClass { #[PHPCR\VersionName] - private $versionName; + private string $versionName; #[PHPCR\VersionCreated] - private $versionCreated; + private \DateTimeInterface $versionCreated; } .. _attref_versioncreated: diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index f8e7ae06a..87320aff3 100644 --- a/docs/en/reference/basic-mapping.rst +++ b/docs/en/reference/basic-mapping.rst @@ -11,7 +11,6 @@ Doctrine provides several different ways for specifying object-document mapping metadata: - PHP Attributes -- Docblock Annotations (deprecated) - XML - YAML @@ -19,7 +18,7 @@ This manual usually mentions PHP attributes 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 Attribute and an Annotation reference chapter. +in more detail. There is also a PHP Attributes reference chapter. .. note:: @@ -167,10 +166,10 @@ Example: class MyPersistentClass { #[PHPCR\Field(type: 'long')] - private $count; + private int $count; #[PHPCR\Field(type: 'string')] - private $name; // type defaults to string + private string $name; // type defaults to string //... } @@ -211,7 +210,7 @@ parameter of the Column attribute follows: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Field(property: 'db_name'"')] - private $myField; + private string $myField; .. code-block:: xml @@ -246,7 +245,7 @@ Unless specified as true, properties are considered single value. use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Field(type: 'string', multivalue: true)] - private $names; + private array $names; .. code-block:: xml @@ -279,10 +278,10 @@ the list keys. use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Field(type: 'string', assoc: '')] - private $names; + private array $names; #[PHPCR\Field(type: 'string', assoc: 'listArraykeys')] - private $list; + private array $list; .. code-block:: xml @@ -398,10 +397,10 @@ the assigned id if either is missing. use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\ParentDocument] - private $parent; + private object $parent; #[PHPCR\Nodename] - private $nodename; + private string $nodename; .. code-block:: xml @@ -443,7 +442,7 @@ representing any PHPCR-ODM document, though.) use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Id] - private $id; + private string $id; .. code-block:: xml @@ -482,7 +481,7 @@ This gives you full control how you want to build the id path. use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Id(strategy: 'repository')] - private $id; + private string $id; .. code-block:: xml @@ -511,10 +510,10 @@ The document code could look like this:: class Document { #[PHPCR\Id(strategy: 'repository')] - private $id; + private string $id; #[PHPCR\Field(type: 'string')] - private $title; + private string $title; //... } diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index 594c423c8..f4a91f6e0 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -41,7 +41,7 @@ the life-time of their registered documents. all references to documents have been removed from the unit of work. This event is not a lifecycle callback; - loadClassMetadata - occurs after mapping metadata for a class has been loaded - from a mapping source (attributes/annotations/xml/yaml). This event is not a lifecycle + from a mapping source (attributes/xml/yaml). This event is not a lifecycle callback. - postLoadTranslation - occurs when a translation of a document has been loaded from the repository. @@ -145,59 +145,59 @@ event occurs. use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\PrePersist] - public function doStuffOnPrePersist() + public function doStuffOnPrePersist(): void { $this->createdAt = date('Y-m-d H:m:s'); } #[PHPCR\PrePersist] - public function doOtherStuffOnPrePersist() + public function doOtherStuffOnPrePersist(): void { $this->value = 'changed from prePersist callback!'; } #[PHPCR\PostPersist] - public function doStuffOnPostPersist() + public function doStuffOnPostPersist(): void { $this->value = 'changed from postPersist callback!'; } #[PHPCR\PostLoad] - public function doStuffOnPostLoad() + public function doStuffOnPostLoad(): void { $this->value = 'changed from postLoad callback!'; } #[PHPCR\PreUpdate] - public function doStuffOnPreUpdate() + public function doStuffOnPreUpdate(): void { $this->value = 'changed from preUpdate callback!'; } #[PHPCR\PreBindTranslation] - public function doStuffOnPreBindTranslation() + public function doStuffOnPreBindTranslation(): void { $this->value = 'changed from preBindTranslation callback!'; } #[PHPCR\PostBindTranslation] - public function doStuffOnPostBindTranslation() + public function doStuffOnPostBindTranslation(): void { $this->value = 'changed from postBindTranslation callback!'; } #[PHPCR\postLoadTranslation] - public function doStuffOnPostLoadTranslation() + public function doStuffOnPostLoadTranslation(): void { $this->value = 'changed from postLoadTranslation callback!'; } #[PHPCR\PreRemoveTranslation] - public function doStuffOnPreRemoveTranslation() + public function doStuffOnPreRemoveTranslation(): void { $this->value = 'changed from preRemoveTranslation callback!'; } #[PHPCR\PostRemoveTranslation] - public function doStuffOnPostRemoveTranslation() + public function doStuffOnPostRemoveTranslation(): void { $this->value = 'changed from postRemoveTranslation callback!'; } diff --git a/docs/en/reference/introduction.rst b/docs/en/reference/introduction.rst index f527d1ae6..fcf7117f9 100644 --- a/docs/en/reference/introduction.rst +++ b/docs/en/reference/introduction.rst @@ -157,58 +157,59 @@ For easy readability, we use the attribute mapping with PHPCR namespace in this namespace Demo; use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ChildrenCollection; #[PHPCR\Document] class MyDocument { #[PHPCR\Id] - private $id; + private string $id; #[PHPCR\ParentDocument] - private $parent; + private object $parent; #[PHPCR\Nodename] - private $name; + private string $name; #[PHPCR\Children] - private $children; + private ChildrenCollection $children; #[PHPCR\Field(type: 'string')] - private $title; + private string $title; #[PHPCR\Field(type: 'string')] - private $content; + private string $content; - public function getId() + public function getId(): string { return $this->id; } - public function getChildren() + public function getChildren(): ChildrenCollection { return $this->children; } - public function setParent($parent) + public function setParent(object $parent): void { $this->parent = $parent; } - public function setName($name) + public function setName(string $name): void { $this->name = $name; } - public function setTitle($title) + public function setTitle(string $title): void { $this->title = $title; } - public function getTitle() + public function getTitle(): string { return $this->title; } - public function setContent($content) + public function setContent(string $content): void { $this->content = $content; } - public function getContent() + public function getContent(): string { return $this->content; } @@ -379,7 +380,7 @@ Lets look at an example of document ``A`` referencing ``B``:: class A { #[PHPCR\ReferenceOne] - private $ref; + private object $ref; ... } diff --git a/docs/en/reference/multilang.rst b/docs/en/reference/multilang.rst index a2847eae4..d094d6642 100644 --- a/docs/en/reference/multilang.rst +++ b/docs/en/reference/multilang.rst @@ -45,26 +45,25 @@ a date to be different depending on the language, you can simply specify the .. code-block:: php - use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; + use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; #[PHPCR\Document(translator: 'attribute')] - */ class MyPersistentClass { #[PHPCR\Locale] - private $locale; + private string $locale; /** * Untranslated property */ #[PHPCR\Field(type: 'date')] - private $publishDate; + private \DateTimeInterface $publishDate; /** * Translated property */ #[PHPCR\Field(type: 'string', translated: true)] - private $topic; + private string $topic; /** * Language specific image @@ -107,7 +106,7 @@ When you manually change the Locale after loading a document, it will be saved a You can set any type of property as translatable, but should only set those that are actually language specific. All other properties should not have that annotation, then they are the same in all languages. -However, you can not set any association annotations to translatable and translations will not propagate +However, you can not map any associations to translatable fields, and translations will not propagate through associations (see the section "Limitations" for an explanation). Having at least one property marked as translatable will require the whole document to @@ -264,7 +263,7 @@ Full Example $doc->topic = 'Un sujet intéressant'; $dm->bindTranslation($doc, 'fr'); - // locale is updated automatically if there is such an annotation + // locale is updated automatically if mapped echo $doc->locale; // fr // Flush to write the changes to the phpcr backend diff --git a/docs/en/reference/phpcr-access.rst b/docs/en/reference/phpcr-access.rst index e1c16e7a5..12bd3eb12 100644 --- a/docs/en/reference/phpcr-access.rst +++ b/docs/en/reference/phpcr-access.rst @@ -32,12 +32,13 @@ This field is populated on find, and as soon as you register the document with t .. code-block:: php use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use PHPCR\NodeInterface; #[PHPCR\Document] class MyPersistentClass { #[PHPCR\Node] - private $node; + private NodeInterface $node; } .. code-block:: xml diff --git a/docs/en/reference/versioning.rst b/docs/en/reference/versioning.rst index 932f65623..65c2432e3 100644 --- a/docs/en/reference/versioning.rst +++ b/docs/en/reference/versioning.rst @@ -80,10 +80,10 @@ Due to implementation limitations, the Locale field is `required` on all transla class MyPersistentClass { #[PHPCR\VersionName] - private $versionName; + private string $versionName; #[PHPCR\VersionCreated] - private $versionCreated; + private \DateTimeInterface $versionCreated; } .. code-block:: xml diff --git a/docs/en/reference/working-with-objects.rst b/docs/en/reference/working-with-objects.rst index f7191275e..d1848d3ec 100644 --- a/docs/en/reference/working-with-objects.rst +++ b/docs/en/reference/working-with-objects.rst @@ -100,28 +100,35 @@ Take the following example of a single ``Article`` document fetched from newly opened DocumentManager:: use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR; + use Doctrine\ODM\PHPCR\ReferrerCollection; #[PHPCR\Document] class Article { #[PHPCR\Id] - private $id; + private string $id; #[PHPCR\Field(type: 'string')] - private $headline; + private string $headline; #[PHPCR\ReferenceOne] - private $author; + private Author $author; #[PHPCR\Referrers(referrerDocument: Comment::class, referencedBy: 'article')] - private $comments; + private ReferrersCollection $comments; public function __construct { $this->comments = new ArrayCollection(); } - public function getAuthor() { return $this->author; } - public function getComments() { return $this->comments; } + public function getAuthor(): Author + { + return $this->author; + } + public function getComments(): ReferrersCollection + { + return $this->comments; + } } $article = $em->find(null, '/cms/article/hello-world'); @@ -718,7 +725,7 @@ By default the ``DocumentManager`` returns a default implementation of ``Doctrine\ODM\PHPCR\DocumentRepository`` when you call ``DocumentManager::getRepository($documentClass)``. You can overwrite this behaviour by specifying the class name of your own Document -Repository in the Annotation, XML or YAML metadata. +Repository in the mapping (PHP Attribute, XML or YAML metadata). In applications that require lots of specialized queries, using a custom repository is the recommended way of grouping these queries @@ -727,16 +734,16 @@ in a central location:: namespace MyDomain\Model; use Doctrine\ODM\PHPCR\DocumentRepository; + use Doctrine\Common\Collections\Collection; #[PHPCR\Document(repositoryClass: UserRepository::class)] class User { - } class UserRepository extends DocumentRepository { - public function getAllAdminUsers() + public function getAllAdminUsers(): Collection { $qb = $this->dm->getQueryBuilder(); // ... build some fancy query