Merge pull request #864 from doctrine/relax-find

explicitly relax the find method

Author: dbu

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 <https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/architecture.html>`_ to get a basic understanding of the Doctrine
 architecture. We will focus on some notable differences here.
 

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

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

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);

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)) {

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