Merge pull request #40 from Sammyjo20/feature/dto-casting

Added new 'CastsToDto' plugin

Author: Sammyjo20

src/Exceptions/MissingDtoCastException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Sammyjo20\Saloon\Exceptions;
+
+class MissingDtoCastException extends SaloonException
+{
+    /**
+     *
+     */
+    public function __construct()
+    {
+        parent::__construct('Saloon was unable to cast to a DTO because a cast was not defined on your request. Add the "CastsToDto" plugin to your request to define a DTO to cast to.');
+    }
+}

src/Http/SaloonResponse.php

@@ -10,6 +10,7 @@
 use Illuminate\Support\Traits\Macroable;
 use GuzzleHttp\Exception\RequestException;
 use Sammyjo20\Saloon\Exceptions\SaloonRequestException;
+use Sammyjo20\Saloon\Exceptions\MissingDtoCastException;
 
 class SaloonResponse
 {
@@ -64,6 +65,13 @@ class SaloonResponse
      */
     protected ?RequestException $guzzleRequestException = null;
 
+    /**
+     * The data transfer object specified on the request if the CastsToDto plugin was added.
+     *
+     * @var object|null
+     */
+    protected ?object $dto = null;
+
     /**
      * Determines if the response has been cached
      *
@@ -467,4 +475,32 @@ public function guessesStatusFromBody(): self
 
         return $this;
     }
+
+    /**
+     * Set the DTO on the response.
+     *
+     * @param object $dto
+     * @return $this
+     */
+    public function setDto(object $dto): self
+    {
+        $this->dto = $dto;
+
+        return $this;
+    }
+
+    /**
+     * Cast the response to a DTO.
+     *
+     * @return object
+     * @throws MissingDtoCastException
+     */
+    public function dto(): object
+    {
+        if (is_null($this->dto)) {
+            throw new MissingDtoCastException;
+        }
+
+        return $this->dto;
+    }
 }

src/Traits/Plugins/CastsToDto.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Sammyjo20\Saloon\Traits\Plugins;
+
+use Sammyjo20\Saloon\Http\SaloonRequest;
+use Sammyjo20\Saloon\Http\SaloonResponse;
+
+trait CastsToDto
+{
+    /**
+     * Boot the castsToDto plugin. This will create a response interceptor that will populate the DTO
+     * property on the response.
+     *
+     * @param SaloonRequest $request
+     * @return void
+     */
+    public function bootCastsToDto(SaloonRequest $request): void
+    {
+        $this->addResponseInterceptor(function (SaloonRequest $request, SaloonResponse $response) {
+            $response->setDto($this->castToDto($response));
+
+            return $response;
+        });
+    }
+
+    /**
+     * Define how Saloon should cast to your DTO.
+     *
+     * @param SaloonResponse $response
+     * @return object
+     */
+    abstract public function castToDto(SaloonResponse $response): object;
+}

tests/Feature/ConnectorRequestTest.php

@@ -1,13 +1,13 @@
 <?php
 
 use Sammyjo20\Saloon\Exceptions\ClassNotFoundException;
-use Sammyjo20\Saloon\Tests\Resources\Requests\UserRequest;
-use Sammyjo20\Saloon\Tests\Resources\Requests\ErrorRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\UserRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\ErrorRequest;
 use Sammyjo20\Saloon\Exceptions\SaloonInvalidRequestException;
 use Sammyjo20\Saloon\Exceptions\SaloonConnectorMethodNotFoundException;
-use Sammyjo20\Saloon\Tests\Resources\Connectors\RequestSelectionConnector;
-use Sammyjo20\Saloon\Tests\Resources\Connectors\InvalidRequestSelectionConnector;
-use Sammyjo20\Saloon\Tests\Resources\Connectors\InvalidDefinedRequestSelectionConnector;
+use Sammyjo20\Saloon\Tests\Fixtures\Connectors\RequestSelectionConnector;
+use Sammyjo20\Saloon\Tests\Fixtures\Connectors\InvalidRequestSelectionConnector;
+use Sammyjo20\Saloon\Tests\Fixtures\Connectors\InvalidDefinedRequestSelectionConnector;
 
 test('you can create a method that will be proxied to a request', function () {
     $connector = new RequestSelectionConnector;

tests/Feature/MockRequestTest.php

@@ -2,13 +2,13 @@
 
 use Sammyjo20\Saloon\Http\MockResponse;
 use Sammyjo20\Saloon\Clients\MockClient;
-use Sammyjo20\Saloon\Tests\Resources\Requests\UserRequest;
-use Sammyjo20\Saloon\Tests\Resources\Requests\ErrorRequest;
-use Sammyjo20\Saloon\Tests\Resources\Connectors\TestConnector;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\UserRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\ErrorRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Connectors\TestConnector;
 use Sammyjo20\Saloon\Exceptions\SaloonNoMockResponsesProvidedException;
-use Sammyjo20\Saloon\Tests\Resources\Connectors\QueryParameterConnector;
-use Sammyjo20\Saloon\Tests\Resources\Requests\DifferentServiceUserRequest;
-use Sammyjo20\Saloon\Tests\Resources\Requests\QueryParameterConnectorRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Connectors\QueryParameterConnector;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\DifferentServiceUserRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\QueryParameterConnectorRequest;
 
 test('a request can be mocked with a sequence', function () {
     $mockClient = new MockClient([

tests/Feature/RequestTest.php

@@ -1,7 +1,7 @@
 <?php
 
-use Sammyjo20\Saloon\Tests\Resources\Requests\UserRequest;
-use Sammyjo20\Saloon\Tests\Resources\Requests\ErrorRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\UserRequest;
+use Sammyjo20\Saloon\Tests\Fixtures\Requests\ErrorRequest;
 
 test('a request can be made successfully', function () {
     $request = new UserRequest();

…s/Connectors/CustomResponseConnector.php …s/Connectors/CustomResponseConnector.phptests/Resources/Connectors/CustomResponseConnector.php renamed to tests/Fixtures/Connectors/CustomResponseConnector.php tests/Resources/Connectors/CustomResponseConnector.php renamed to tests/Fixtures/Connectors/CustomResponseConnector.php

@@ -1,9 +1,9 @@
 <?php
 
-namespace Sammyjo20\Saloon\Tests\Resources\Connectors;
+namespace Sammyjo20\Saloon\Tests\Fixtures\Connectors;
 
 use Sammyjo20\Saloon\Http\SaloonConnector;
-use Sammyjo20\Saloon\Tests\Resources\Responses\CustomResponse;
+use Sammyjo20\Saloon\Tests\Fixtures\Responses\CustomResponse;
 
 class CustomResponseConnector extends SaloonConnector
 {

…Connectors/DifferentServiceConnector.php …Connectors/DifferentServiceConnector.phptests/Resources/Connectors/DifferentServiceConnector.php renamed to tests/Fixtures/Connectors/DifferentServiceConnector.php tests/Resources/Connectors/DifferentServiceConnector.php renamed to tests/Fixtures/Connectors/DifferentServiceConnector.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Sammyjo20\Saloon\Tests\Resources\Connectors;
+namespace Sammyjo20\Saloon\Tests\Fixtures\Connectors;
 
 use Sammyjo20\Saloon\Http\SaloonConnector;
 use Sammyjo20\Saloon\Traits\Plugins\AcceptsJson;

tests/Fixtures/Connectors/DtoConnector.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Sammyjo20\Saloon\Tests\Fixtures\Connectors;
+
+use Sammyjo20\Saloon\Http\SaloonResponse;
+use Sammyjo20\Saloon\Http\SaloonConnector;
+use Sammyjo20\Saloon\Traits\Plugins\CastsToDto;
+use Sammyjo20\Saloon\Traits\Plugins\AcceptsJson;
+use Sammyjo20\Saloon\Tests\Fixtures\Data\ApiResponse;
+
+class DtoConnector extends SaloonConnector
+{
+    use AcceptsJson;
+    use CastsToDto;
+
+    /**
+     * Define the base url of the api.
+     *
+     * @return string
+     */
+    public function defineBaseUrl(): string
+    {
+        return apiUrl();
+    }
+
+    /**
+     * Define the base headers that will be applied in every request.
+     *
+     * @return string[]
+     */
+    public function defaultHeaders(): array
+    {
+        return [];
+    }
+
+    /**
+     * @param SaloonResponse $response
+     * @return object
+     */
+    public function castToDto(SaloonResponse $response): object
+    {
+        return ApiResponse::fromSaloon($response);
+    }
+}

…sources/Connectors/ExtendedConnector.php …ixtures/Connectors/ExtendedConnector.phptests/Resources/Connectors/ExtendedConnector.php renamed to tests/Fixtures/Connectors/ExtendedConnector.php tests/Resources/Connectors/ExtendedConnector.php renamed to tests/Fixtures/Connectors/ExtendedConnector.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Sammyjo20\Saloon\Tests\Resources\Connectors;
+namespace Sammyjo20\Saloon\Tests\Fixtures\Connectors;
 
 class ExtendedConnector extends TestConnector
 {