Make Realtime Database value objects final and readonly

Author: jeromegamez

.php-cs-fixer.dist.php

@@ -25,6 +25,9 @@
         'method_argument_space' => [
             'attribute_placement' => 'standalone', // same_line can break PHP <8.2
         ],
+        'no_blank_lines_after_phpdoc' => true,
+        'no_empty_phpdoc' => true,
+        'no_unneeded_braces' => true,
         'no_unused_imports' => true,
         'ordered_imports' => [
             'imports_order' => [
@@ -34,6 +37,9 @@
             ],
             'sort_algorithm' => 'alpha',
         ],
+        'phpdoc_align' => [
+            'align' => 'left',
+        ],
         'php_unit_method_casing' => [
             'case' => 'camel_case',
         ],

CHANGELOG.md

@@ -15,6 +15,7 @@ If it saves you or your team time, please consider [sponsoring its development](
 * Type declarations have been simplified to reduce runtime overhead (e.g., `Stringable|string` to `string`).
 * The transitional `Kreait\Firebase\Contract\Transitional\FederatedUserFetcher::getUserByProviderUid()` method
   has been moved into the `Kreait\Firebase\Contract\Auth` interface
+* Realtime Database objects considered value objects have been made final and readonly
 
 See **[UPGRADE-8.0](UPGRADE-8.0.md) for more details on the changes between 7.x and 8.0.**
 

UPGRADE-8.0.md

@@ -11,6 +11,7 @@ from 7.x to 8.0.
   supported versions are 8.3, 8.4, and 8.5.
 * [Firebase Dynamic Links was shut down on August 25th, 2025](https://firebase.google.com/support/dynamic-links-faq)
   and has been removed from the SDK.
+* Realtime Database objects considered value objects have been made final and readonly 
 
 ### Type simplifications to reduce runtime overhead
 
@@ -29,6 +30,10 @@ The following list has been generated with [roave/backward-compatibility-check](
 
 ```
 [BC] ADDED: Method getUserByProviderUid() was added to interface Kreait\Firebase\Contract\Auth
+[BC] CHANGED: Class Kreait\Firebase\Database\Query became final
+[BC] CHANGED: Class Kreait\Firebase\Database\Reference became final
+[BC] CHANGED: Class Kreait\Firebase\Database\RuleSet became final
+[BC] CHANGED: Class Kreait\Firebase\Database\Snapshot became final
 [BC] CHANGED: Default parameter value for parameter $code of Kreait\Firebase\Exception\Database\TransactionFailed#__construct() changed from 0 to NULL
 [BC] CHANGED: Default parameter value for parameter $code of Kreait\Firebase\Exception\Database\UnsupportedQuery#__construct() changed from 0 to NULL
 [BC] CHANGED: The number of required arguments for Kreait\Firebase\Exception\Database\UnsupportedQuery#__construct() increased from 1 to 2

src/Firebase/Database/Query.php

@@ -14,6 +14,7 @@
 use Kreait\Firebase\Database\Query\Filter\StartAfter;
 use Kreait\Firebase\Database\Query\Filter\StartAt;
 use Kreait\Firebase\Database\Query\Sorter;
+use Kreait\Firebase\Database\Query\Sorter\Noop;
 use Kreait\Firebase\Database\Query\Sorter\OrderByChild;
 use Kreait\Firebase\Database\Query\Sorter\OrderByKey;
 use Kreait\Firebase\Database\Query\Sorter\OrderByValue;
@@ -34,19 +35,19 @@
  * {@see getSnapshot()} or {@see getValue()} method. You will only receive
  * Snapshots for the subset of the data that matches your query.
  */
-class Query implements Stringable
+final readonly class Query implements Stringable
 {
-    /**
-     * @var Filter[]
-     */
-    private array $filters = [];
-
-    private ?Sorter $sorter = null;
-
     /**
      * @internal
+     *
+     * @param list<Filter> $filters
      */
-    public function __construct(private readonly Reference $reference, private readonly ApiClient $apiClient)
+    public function __construct(
+        private Reference $reference,
+        private ApiClient $apiClient,
+        private array $filters,
+        private Sorter $sorter,
+    )
     {
     }
 
@@ -91,9 +92,7 @@ public function getSnapshot(): Snapshot
             );
         }
 
-        if ($this->sorter !== null) {
-            $value = $this->sorter->modifyValue($value);
-        }
+        $value = $this->sorter->modifyValue($value);
 
         foreach ($this->filters as $filter) {
             $value = $filter->modifyValue($value);
@@ -253,10 +252,7 @@ public function shallow(): self
     public function getUri(): UriInterface
     {
         $uri = $this->reference->getUri();
-
-        if ($this->sorter !== null) {
-            $uri = $this->sorter->modifyUri($uri);
-        }
+        $uri = $this->sorter->modifyUri($uri);
 
         foreach ($this->filters as $filter) {
             $uri = $filter->modifyUri($uri);
@@ -267,21 +263,25 @@ public function getUri(): UriInterface
 
     private function withAddedFilter(Filter $filter): self
     {
-        $query = clone $this;
-        $query->filters[] = $filter;
-
-        return $query;
+        return new self(
+            $this->reference,
+            $this->apiClient,
+            [...$this->filters, $filter],
+            $this->sorter
+        );
     }
 
     private function withSorter(Sorter $sorter): self
     {
-        if ($this->sorter !== null) {
+        if (!($this->sorter instanceof Noop)) {
             throw new UnsupportedQuery($this, 'This query is already ordered.');
         }
 
-        $query = clone $this;
-        $query->sorter = $sorter;
-
-        return $query;
+        return new self(
+            $this->reference,
+            $this->apiClient,
+            $this->filters,
+            $sorter
+        );
     }
 }

src/Firebase/Database/Query/Sorter/Noop.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Database\Query\Sorter;
+
+use Kreait\Firebase\Database\Query\Sorter;
+use Psr\Http\Message\UriInterface;
+
+/**
+ * @internal
+ */
+final readonly class Noop implements Sorter
+{
+    public function modifyUri(UriInterface $uri): UriInterface
+    {
+        return $uri;
+    }
+
+    public function modifyValue(mixed $value): mixed
+    {
+        return $value;
+    }
+}

src/Firebase/Database/Reference.php

@@ -4,6 +4,7 @@
 
 namespace Kreait\Firebase\Database;
 
+use Kreait\Firebase\Database\Query\Sorter\Noop;
 use Kreait\Firebase\Exception\DatabaseException;
 use Kreait\Firebase\Exception\InvalidArgumentException;
 use Kreait\Firebase\Exception\OutOfRangeException;
@@ -24,14 +25,14 @@
  * A Reference represents a specific location in your database and can be used
  * for reading or writing data to that database location.
  */
-class Reference implements Stringable
+final readonly class Reference implements Stringable
 {
     /**
      * @internal
      */
     public function __construct(
-        private readonly UriInterface $uri,
-        private readonly ApiClient $apiClient,
+        private UriInterface $uri,
+        private ApiClient $apiClient,
     ) {
     }
 
@@ -42,7 +43,7 @@ public function __construct(
      */
     public function __toString(): string
     {
-        return (string) $this->getUri();
+        return (string) $this->uri;
     }
 
     /**
@@ -74,12 +75,12 @@ public function getPath(): string
      */
     public function getParent(): self
     {
-        $parentPath = dirname($this->getPath());
-
-        if ($parentPath === '.') {
+        if ($this->getPath() === '') {
             throw new OutOfRangeException('Cannot get parent of root reference');
         }
 
+        $parentPath = dirname($this->getPath());
+
         return new self($this->uri->withPath('/'.ltrim($parentPath, '/')), $this->apiClient);
     }
 
@@ -388,6 +389,6 @@ public function getUri(): UriInterface
      */
     private function query(): Query
     {
-        return new Query($this, $this->apiClient);
+        return new Query($this, $this->apiClient, [], new Noop());
     }
 }

src/Firebase/Database/RuleSet.php

@@ -8,12 +8,12 @@
 
 use function array_key_exists;
 
-class RuleSet implements JsonSerializable
+final readonly class RuleSet implements JsonSerializable
 {
     /**
      * @var array<string, array<mixed>>
      */
-    private readonly array $rules;
+    private array $rules;
 
     /**
      * @param array<string, array<mixed>> $rules

src/Firebase/Database/Snapshot.php

@@ -24,12 +24,12 @@
  * Alternatively, you can traverse into the snapshot by calling {@see getChild()}
  * to return child snapshots (which you could then call {@see getValue()} on).
  */
-class Snapshot
+final readonly class Snapshot
 {
     /**
      * @internal
      */
-    public function __construct(private readonly Reference $reference, private readonly mixed $value)
+    public function __construct(private Reference $reference, private mixed $value)
     {
     }