Add super method

README.md

@@ -256,3 +256,4 @@ This library also comes with its own Firestore `Entity` that handles Google's ti
 conversions and these methods to access metadata about the underlying Firestore document:
 * `document(?DocumentReference $document = null): ?DocumentReference` *Gets or sets the document*
 * `id(): string`
+* `super(): ?DocumentReference` *Gets an Entity's parent Entity, if it is from a subcollection*

src/Firestore/Entity.php

@@ -7,6 +7,7 @@
 use DateTime;
 use Google\Cloud\Core\Timestamp;
 use Google\Cloud\Firestore\DocumentReference;
+use UnexpectedValueException;
 
 class Entity extends FrameworkEntity
 {
@@ -46,6 +47,20 @@ final public function document(?DocumentReference $document = null): ?DocumentRe
         return $this->document;
     }
 
+    /**
+     * Returns the next higher DocumentReference for nested objects,
+     * or null if not part of a subcollection.
+     */
+    public function super(): ?DocumentReference
+    {
+        if (null === $reference = $this->document()) {
+            throw new UnexpectedValueException('Entity must exist before accessing parent.');
+        }
+
+        // The parent is the subcollection, its parent (if it exists) is a document
+        return $reference->parent()->parent();
+    }
+
     /**
      * Converts the given item into a Time object.
      * Adds support for Google's Timestamp

tests/firestore/EntityTest.php

@@ -2,6 +2,8 @@
 
 use CodeIgniter\I18n\Time;
 use Google\Cloud\Core\Timestamp;
+use Google\Cloud\Firestore\DocumentReference;
+use Tests\Support\Collections\FruitCollection;
 use Tests\Support\FirestoreTestCase;
 
 /**
@@ -55,4 +57,33 @@ public function testMutateDateSupportsNull()
 
         $this->assertNull($result);
     }
+
+    public function testSuperRequiresDocument()
+    {
+        $fruit = $this->collection->fake();
+
+        $this->expectException('UnexpectedValueException');
+        $this->expectExceptionMessage('Entity must exist before accessing parent.');
+
+        $this->assertNull($fruit->super());
+    }
+
+    public function testSuperIsNull()
+    {
+        $fruit = $this->collection->make();
+
+        $this->assertNull($fruit->super());
+    }
+
+    public function testSuperReturnsCollectionDocumentParent()
+    {
+        $fruit = $this->collection->make();
+        $foods = collection(FruitCollection::class, $fruit);
+        $food  = $foods->add(['name' => 'food']);
+
+        $result = $food->super();
+
+        $this->assertInstanceOf(DocumentReference::class, $result);
+        $this->assertSame($fruit->id(), $result->id());
+    }
 }