Add support for shallow GET requests

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Better handling of server errors
     + Instead of using hard coded exception messages for assumed server errors, a single server error exception now includes the server's error message, if available.
+- It is now possible to use the `shallow` parameter when performing a GET request. See [the Firebase Docs on Query Parameters](https://www.firebase.com/docs/rest/api/#section-query-parameters) for a detailed description.
 
 ## 0.1.1 - 2015-01-09
 

README.md

@@ -50,6 +50,8 @@ $firebase->set(['name' => 'John Doe', 'email' => '[email protected]'], 'data/users/jo
 $firebase->update(['email' => '[email protected]'], 'data/users/john');
 $firebase->push(['name' => 'Jane Doe', 'email' => '[email protected]'], 'data/users');
 $firebase->delete('data/users/john');
+$firebase->get('data/users');
+$firebase->get('data/users', ['shallow' => true]); // Limit the depth of the data received
 
 ```
 

src/Firebase.php

@@ -62,9 +62,9 @@ public function getLogger()
     /**
      * {@inheritdoc}
      */
-    public function get($location)
+    public function get($location, array $options = [])
     {
-        return $this->send($location, RequestInterface::METHOD_GET);
+        return $this->send($location, RequestInterface::METHOD_GET, null, $options);
     }
 
     /**
@@ -106,12 +106,13 @@ public function delete($location)
      * @param string            $location The location.
      * @param string            $method   The HTTP method.
      * @param array|object|null $data     The data.
+     * @param array             $options  Request options
      *
      * @throws FirebaseException
      *
      * @return array|string|void The processed response data.
      */
-    private function send($location, $method, $data = null)
+    private function send($location, $method, $data = null, array $options = [])
     {
         $location = (string) $location; // In case it is null
 
@@ -122,13 +123,18 @@ private function send($location, $method, $data = null)
         // When $location is null, the relative URL will be '/.json', which is okay
         $relativeUrl = sprintf('/%s.json', Utils::normalizeLocation($location));
 
+        $requestParams = $this->createRequestParams($method, $options);
+        if (count($requestParams)) {
+            $relativeUrl = sprintf('%s?%s', $relativeUrl, http_build_query($requestParams, '', '&'));
+        }
+
         $headers = [
             'accept' => 'application/json',
             'accept-charset' => 'utf-8',
         ];
 
-        // It would have been easier to write $this->http->send(…) but this would not give us a request object
-        // to debug later
+        // It would have been easier to write $this->http->send(…) but this would not
+        // give us a request object to debug later
         $request = $this->http->getConfiguration()->getMessageFactory()->createRequest(
             $relativeUrl,
             $method,
@@ -165,4 +171,25 @@ private function send($location, $method, $data = null)
 
         return json_decode($contents, true);
     }
+
+    /**
+     * Returns an array of request parameters, based on the given method and options.
+     *
+     * @param string $method
+     * @param array $options
+     * @return array The request params.
+     */
+    private function createRequestParams($method, array $options)
+    {
+        $requestParams = [];
+        switch($method) {
+            case RequestInterface::METHOD_GET:
+                if (isset($options['shallow']) && true === $options['shallow']) {
+                    $requestParams['shallow'] = 'true';
+                }
+                break;
+        }
+
+        return $requestParams;
+    }
 }

src/FirebaseInterface.php

@@ -31,9 +31,10 @@ public function getLogger();
      * Returns the data at the given location, or null if not defined.
      *
      * @param  string|null $location The location.
+     * @param  array $options The options.
      * @return array|null  The data at the given location, or null if not defined.
      */
-    public function get($location);
+    public function get($location, array $options = []);
 
     /**
      * Write or replace data at the given location.
@@ -54,7 +55,7 @@ public function set($data, $location);
     public function push($data, $location);
 
     /**
-     * Update the given fields in a .
+     * Update the given field(s) at the given location.
      *
      * @param  array|object $data The fields
      * @param  string       $location
@@ -63,7 +64,7 @@ public function push($data, $location);
     public function update($data, $location);
 
     /**
-     * Deletes the given location. If null,
+     * Deletes the given location.
      *
      * @param  string $location
      * @return void

src/Reference.php

@@ -90,10 +90,10 @@ public function delete($location = null)
     /**
      * {@inheritdoc}
      */
-    public function get($location = null)
+    public function get($location = null, array $options = [])
     {
         $fullLocation = Utils::normalizeLocation(sprintf('%s/%s', $this->referenceUrl, $location));
 
-        return $this->firebase->get($fullLocation);
+        return $this->firebase->get($fullLocation, $options);
     }
 }

src/ReferenceInterface.php

@@ -13,7 +13,7 @@ interface ReferenceInterface extends FirebaseInterface
     /**
      * {@inheritdoc}
      */
-    public function get($location = null);
+    public function get($location = null, array $options = []);
 
     /**
      * {@inheritdoc}