diff --git a/docs/en/reference/architecture.rst b/docs/en/reference/architecture.rst index c8dd5486c..d55ddb1fe 100644 --- a/docs/en/reference/architecture.rst +++ b/docs/en/reference/architecture.rst @@ -1,7 +1,7 @@ Architecture ============ -The architecture of the PHPCR-ODM is similar to that of Doctrine 2 ORM. Please read +The architecture of the PHPCR-ODM is similar to that of Doctrine ORM. Please read the `ORM architecture chapter `_ to get a basic understanding of the Doctrine architecture. We will focus on some notable differences here. diff --git a/docs/en/reference/installation-configuration.rst b/docs/en/reference/installation-configuration.rst index c2a698b51..7c366ddd6 100644 --- a/docs/en/reference/installation-configuration.rst +++ b/docs/en/reference/installation-configuration.rst @@ -421,7 +421,7 @@ Proxy Objects A proxy object is an object that is put in place or used instead of the "real" object. A proxy object can add behavior to the object -being proxied without that object being aware of it. In Doctrine 2, +being proxied without that object being aware of it. In Doctrine, proxy objects are used to realize several features but mainly for transparent lazy-loading. @@ -431,7 +431,7 @@ of the objects. This is an essential property as without it there would always be fragile partial objects at the outer edges of your object graph. -Doctrine 2 implements a variant of the proxy pattern where it +Doctrine implements a variant of the proxy pattern where it generates classes that extend your entity classes and adds lazy-loading capabilities to them. Doctrine can then give you an instance of such a proxy class whenever you request an object of @@ -498,7 +498,7 @@ each time you change anything on your class or mapping: Multiple Metadata Sources ~~~~~~~~~~~~~~~~~~~~~~~~~ -When using different components using Doctrine 2 you may end up +When using different components using Doctrine you may end up with them using two different metadata drivers, for example XML and YAML. You can use the DriverChain Metadata implementations to aggregate these drivers based on namespaces:: diff --git a/docs/en/reference/working-with-objects.rst b/docs/en/reference/working-with-objects.rst index d1848d3ec..1f1948170 100644 --- a/docs/en/reference/working-with-objects.rst +++ b/docs/en/reference/working-with-objects.rst @@ -49,11 +49,12 @@ with the headline "Hello World" with the ID ``/cms/article/hello-world``:: has a table per class and thus always needs the document class name, PHPCR-ODM has one tree for all documents. The above call will find you whatever document is at that path. Note that you may optionally specify - the class name to have PHPCR-ODM detect if the document is not of the - expected type. + the class name to have PHPCR-ODM check if the document is not of the + expected type. On a class mismatch, PHPCR-ODM treats the lookup as a not + found and returns ``null``. In this case, the article is retrieved from the document manager twice, -but modified in between. Doctrine 2 realizes that it is the same ID and will +but modified in between. Doctrine realizes that it is the same ID and will only ever give you access to one instance of the Article with ID ``/cms/article/hello-world``, no matter how often do you retrieve it from the ``DocumentManager`` and even no matter what kind of Query method you are @@ -619,16 +620,16 @@ example:: $user = $em->find(User::class, $id); The return value is either the found document instance or null if no -instance could be found with the given identifier. +instance of the specified class can be found with the given identifier. If you need several documents and know their paths, you can have a considerable performance gain by using ``DocumentManager::findMany(null, $ids)`` as then all those documents are loaded from the repository in one request. You can also specify the class name instead of null to filter to only find -instances of that class. If you go through the repository for a document class -this is equivalent to calling find on the ``DocumentManager`` with that document -class. +instances of that class. If you call ``find`` on the repository of a document +class, this is equivalent to calling ``find`` on the ``DocumentManager`` with +that document class. By Simple Conditions diff --git a/lib/Doctrine/ODM/PHPCR/Decorator/DocumentManagerDecorator.php b/lib/Doctrine/ODM/PHPCR/Decorator/DocumentManagerDecorator.php index 7064623c9..65346c171 100644 --- a/lib/Doctrine/ODM/PHPCR/Decorator/DocumentManagerDecorator.php +++ b/lib/Doctrine/ODM/PHPCR/Decorator/DocumentManagerDecorator.php @@ -88,6 +88,11 @@ public function isOpen(): bool return $this->wrapped->isOpen(); } + public function find(?string $className, $id): ?object + { + return $this->wrapped->find($className, $id); + } + public function findMany(?string $className, array $ids): Collection { return $this->wrapped->findMany($className, $ids); diff --git a/lib/Doctrine/ODM/PHPCR/DocumentManager.php b/lib/Doctrine/ODM/PHPCR/DocumentManager.php index df639fb4f..6ac78eedd 100644 --- a/lib/Doctrine/ODM/PHPCR/DocumentManager.php +++ b/lib/Doctrine/ODM/PHPCR/DocumentManager.php @@ -173,24 +173,7 @@ public function getClassMetadata($className): ClassMetadata return $this->metadataFactory->getMetadataFor($className); } - /** - * {@inheritdoc} - * - * Find the Document with the given id. - * - * Will return null if the document was not found. A document is considered - * not found if the data at $id is not instance of of the specified - * $className. To get the document regardless of its class, pass null. - * - * If the document is translatable, then the language chooser strategy is - * used to load the best suited language for the translatable fields. - * - * @param string|null $className optional object class name to use - * @param string $id the path or uuid of the document to find - * - * @return object|null the document if found, otherwise null - */ - public function find($className, $id): ?object + public function find(?string $className, $id): ?object { try { if (UUIDHelper::isUUID($id)) { diff --git a/lib/Doctrine/ODM/PHPCR/DocumentManagerInterface.php b/lib/Doctrine/ODM/PHPCR/DocumentManagerInterface.php index 1280d66d5..d960882c0 100644 --- a/lib/Doctrine/ODM/PHPCR/DocumentManagerInterface.php +++ b/lib/Doctrine/ODM/PHPCR/DocumentManagerInterface.php @@ -109,6 +109,27 @@ public function getConfiguration(): Configuration; */ public function isOpen(): bool; + /** + * {@inheritdoc} + * + * Overwritten to make the $className argument nullable. + * + * Find the Document with the given id. + * + * Will return null if the document was not found. A document is also + * considered not found if the data at $id is not instance of the specified + * $className. To get the document regardless of its class, pass null. + * + * If the document is translatable, then the language chooser strategy is + * used to load the best suited language for the translatable fields. + * + * @param string|null $className optional object class name to use + * @param string $id the path or uuid of the document to find + * + * @return object|null the document if found, otherwise null + */ + public function find(?string $className, $id): ?object; + /** * Finds many documents by id. *