Merge pull request #420 from Braunson/v3

Feature | Added support to Response object method to now accept a dot notation like json()

.github/workflows/php-cs-fixer.yml

@@ -13,6 +13,10 @@ on:
 permissions:
   contents: write
 
+concurrency:
+  group: ${{ github.head_ref || github.ref || github.run_id }}_php_cs_fixer
+  cancel-in-progress: true
+
 jobs:
   php-cs-fixer:
     runs-on: ubuntu-latest

.github/workflows/phpstan.yml

@@ -10,6 +10,10 @@ on:
     branches:
       - '*'
 
+concurrency:
+  group: ${{ github.head_ref || github.ref || github.run_id }}_phpstan
+  cancel-in-progress: true
+
 jobs:
   phpstan:
     name: phpstan

.github/workflows/tests.yml

@@ -13,6 +13,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.head_ref || github.ref || github.run_id }}_tests
+  cancel-in-progress: true
+
 jobs:
   tests:
     runs-on: ${{ matrix.os }}

src/Helpers/ObjectHelpers.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Saloon\Helpers;
+
+/**
+ * @internal
+ */
+final class ObjectHelpers
+{
+    /**
+     * Get an item from an object using "dot" notation.
+     */
+    public static function get(object $object, string $key, mixed $default = null): mixed
+    {
+        // Split the dot notation into individual keys
+
+        $keys = explode('.', $key);
+
+        // Navigate through the object properties
+
+        foreach ($keys as $dot) {
+            // Check if the object is an array or object and if the key exists
+            if (is_object($object) && isset($object->{$dot})) {
+                $object = $object->{$dot};
+            } elseif (is_array($object) && isset($object[$dot])) {
+                $object = $object[$dot];
+            } else {
+                // Return null if the key doesn't exist
+                return null;
+            }
+        }
+
+        return $object;
+    }
+}

src/Http/Response.php

@@ -10,6 +10,7 @@
 use Saloon\Traits\Macroable;
 use InvalidArgumentException;
 use Saloon\Helpers\ArrayHelpers;
+use Saloon\Helpers\ObjectHelpers;
 use Saloon\XmlWrangler\XmlReader;
 use Illuminate\Support\Collection;
 use Saloon\Contracts\FakeResponse;
@@ -53,6 +54,11 @@ class Response
      */
     protected array $decodedJson;
 
+    /**
+     * The decoded JSON response object.
+     */
+    protected mixed $decodedJsonObject;
+
     /**
      * The decoded XML response.
      */
@@ -223,19 +229,27 @@ public function array(int|string|null $key = null, mixed $default = null): mixed
     }
 
     /**
-     * Get the JSON decoded body of the response as an object.
+     * Get the JSON decoded body of the response as an object or scalar value.
      */
-    public function object(): object
+    public function object(string|int|null $key = null, mixed $default = null): mixed
     {
-        return json_decode($this->body(), false, 512, JSON_THROW_ON_ERROR);
+        if (! isset($this->decodedJsonObject)) {
+            $this->decodedJsonObject = json_decode($this->body() ?: '{}', false, 512, JSON_THROW_ON_ERROR);
+        }
+
+        if (is_null($key)) {
+            return $this->decodedJsonObject;
+        }
+
+        return ObjectHelpers::get($this->decodedJsonObject, (string)$key, $default);
     }
 
     /**
      * Convert the XML response into a SimpleXMLElement.
      *
      * Suitable for reading small, simple XML responses but not suitable for
      * more advanced XML responses with namespaces and prefixes. Consider
-     * using the xmlReader method instead for better compatability.
+     * using the xmlReader method instead for better compatibility.
      *
      * @see https://www.php.net/manual/en/book.simplexml.php
      */

tests/Unit/ResponseTest.php

@@ -137,6 +137,23 @@
     expect($response)->object()->toEqual($dataAsObject);
 });
 
+test('the object method with a dot notation key value will return a nested string', function () {
+    $data = [
+        'contacts' => [
+            ['name' => 'Sam', 'work' => 'Codepotato'],
+            ['name' => 'Braunson', 'work' => 'Geekybeaver'],
+        ],
+    ];
+
+    $mockClient = new MockClient([
+        MockResponse::make($data, 500),
+    ]);
+
+    $response = connector()->send(new UserRequest, $mockClient);
+
+    expect($response)->object('contacts.1.name')->toEqual('Braunson');
+});
+
 test('the collect method will return a collection', function () {
     $mockClient = new MockClient([
         MockResponse::make(['name' => 'Sam', 'work' => 'Codepotato'], 500),