changes

Author: yurikuzn

src/Client.php

@@ -4,6 +4,8 @@
 namespace Espo\ApiClient;
 
 use CurlHandle;
+use Espo\ApiClient\Exception\Error;
+use Espo\ApiClient\Exception\ResponseError;
 use InvalidArgumentException;
 use JsonException;
 use RuntimeException;
@@ -71,15 +73,16 @@ public function setSecretKey(?string $secretKey): self
      * @param string $path A relative URL path. E.g. `Account/00000000000id`.
      * @param array<int, mixed>|array<string, mixed>|stdClass|null $data Payload data.
      * @param Header[] $headers Headers.
-     * @return stdClass|array<int, mixed>|string
-     * @throws Exception
+     * @return Response A response (on success).
+     * @throws Error
+     * @throws ResponseError On error occurred on request.
      */
     public function request(
         string $method,
         string $path,
         mixed $data = null,
         array $headers = []
-    ): stdClass|array|string {
+    ): Response {
 
         $method = strtoupper($method);
         $this->lastCh = null;
@@ -121,7 +124,7 @@ public function request(
         curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
         curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
         curl_setopt($ch, CURLOPT_HEADER, true);
-        
+
         if ($this->port !== null) {
             curl_setopt($ch, CURLOPT_PORT, $this->port);
         }
@@ -194,7 +197,7 @@ public function request(
         $lastResponse = curl_exec($ch);
 
         if ($lastResponse === false) {
-            throw new Exception('CURL exec failure.', 0);
+            throw new Error('CURL exec failure.', 0);
         }
 
         $this->lastCh = $ch;
@@ -203,47 +206,49 @@ public function request(
         $responseCode = $this->getResponseHttpCode();
         $responseContentType = $this->getResponseContentType();
 
+        $response = new Response(
+            $responseCode ?? 0,
+            $responseContentType,
+            $parsedResponse['header'],
+            $parsedResponse['body'],
+        );
+
         curl_close($ch);
 
         if (
-            ($responseCode !== null && $responseCode >= 200 && $responseCode < 300) &&
-            !empty($parsedResponse['body'])
+            $responseCode !== null &&
+            $responseCode >= 200 &&
+            $responseCode < 300
         ) {
-            if ($responseContentType === 'application/json') {
-                return json_decode($parsedResponse['body']);
-            }
-
-            return $parsedResponse['body'];
+            return $response;
         }
 
         $responseHeaders = $this->normalizeHeader($parsedResponse['header']);
+        $errorMessage = $responseHeaders['X-Status-Reason'] ?? '';
 
-        $errorMessage = $responseHeaders['X-Status-Reason'] ?? 'Unknown Error';
-
-        throw (new Exception($errorMessage, $responseCode ?? 0))
-            ->withBody($parsedResponse['body']);
+        throw new ResponseError($response, $errorMessage, $responseCode ?? 0);
     }
 
     /**
      * Get a response content type.
      */
-    public function getResponseContentType(): ?string
+    private function getResponseContentType(): ?string
     {
         return $this->getInfo(CURLINFO_CONTENT_TYPE);
     }
 
     /**
      * Get a response total time.
      */
-    public function getResponseTotalTime(): ?int
+    private function getResponseTotalTime(): ?int
     {
         return $this->getInfo(CURLINFO_TOTAL_TIME);
     }
 
     /**
      * Get a response code.
      */
-    public function getResponseHttpCode(): ?int
+    private function getResponseHttpCode(): ?int
     {
         return $this->getInfo(CURLINFO_HTTP_CODE);
     }

src/Exception.php

@@ -0,0 +1,9 @@
+<?php
+/* (c) EspoCRM */
+
+namespace Espo\ApiClient\Exception;
+
+use Exception;
+
+class Error extends Exception
+{}

src/Exception/Error.php

@@ -0,0 +1,29 @@
+<?php
+/* (c) EspoCRM */
+
+namespace Espo\ApiClient\Exception;
+
+use Espo\ApiClient\Response;
+
+/**
+ * Use getCode to obtain HTTP error code. Codes:
+ * - 400 Bad Request (bad parameters or validation error);
+ * - 404 Not Found (not existing URL path or record not found);
+ * - 403 Forbidden (no access to scope or to record);
+ * - 409 Conflict (can be that a duplicate record already exists).
+ */
+class ResponseError extends Error
+{
+    final public function __construct(
+        private Response $response,
+        string $message = '',
+        int $code = 0
+    ) {
+        parent::__construct($message, $code);
+    }
+
+    public function getResponse(): Response
+    {
+        return $this->response;
+    }
+}

src/Exception/ResponseError.php

@@ -0,0 +1,43 @@
+<?php
+/* (c) EspoCRM */
+
+namespace Espo\ApiClient;
+
+class Response
+{
+    public function __construct(
+        private int $code,
+        private ?string $contentType,
+        private string $headersPart,
+        private string $bodyPart
+    ) {}
+
+    public function getCode(): int
+    {
+        return $this->code;
+    }
+
+    public function getHeadersPart(): string
+    {
+        return $this->headersPart;
+    }
+
+    public function getBodyPart(): string
+    {
+        return $this->bodyPart;
+    }
+
+    public function getContentType(): ?string
+    {
+        return $this->contentType;
+    }
+
+    public function getParsedBody(): mixed
+    {
+        if ($this->getContentType() === 'application/json') {
+            return json_decode($this->getBodyPart());
+        }
+
+        return null;
+    }
+}