chore: add result validation

Author: ju5t

src/Api.php

@@ -4,75 +4,117 @@
 
 use Illuminate\Http\Client\ConnectionException;
 use Illuminate\Http\Client\Response;
+use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Http;
 use JsonException;
 use Sensson\DirectAdmin\Exceptions\ConnectionFailed;
+use Sensson\DirectAdmin\Exceptions\InvalidResponse;
 
 class Api
 {
     public bool $debug = false;
 
-    public bool $json = true;
-
     /**
+     * Call the DirectAdmin API by giving it an API command and some
+     * parameters. This will return an array with processed data.
+     *
      * @throws ConnectionFailed
+     * @throws InvalidResponse
      */
-    public function call(string $command, array $params = []): array
+    public function call(string $command, array $params = []): Collection
     {
-        $queryParams = $this->json
-            ? ['json' => true]
-            : [];
-
         try {
             $response = Http::acceptJson()
                 ->withBasicAuth(config('directadmin.username'), config('directadmin.password'))
-                ->withQueryParameters($queryParams)
+                ->withOptions($this->getHttpOptions())
+                ->withQueryParameters($this->getQueryParams())
                 ->post(config('directadmin.baseUrl').'/'.strtoupper($command), $params);
         } catch (ConnectionException $e) {
             throw new ConnectionFailed('Connection failed: '.$e->getMessage());
         }
 
-        return $this->process($response);
+        return $this->processResponse($response);
     }
 
-    public function withoutJson(): static
+    /**
+     * Enable debug mode for HTTP requests. This can help identify
+     * issues with the DirectAdmin server.
+     */
+    public function debug(): static
     {
-        $this->json = false;
+        $this->debug = true;
 
         return $this;
     }
 
     /**
+     * Process the response that's returned by the DirectAdmin API
+     * and prepare it for further processing by third party code.
+     *
      * @throws ConnectionFailed
+     * @throws InvalidResponse
      */
-    protected function process(Response $response): array
+    protected function processResponse(Response $response): Collection
     {
-        if (! $response->successful()) {
+        if (! $response->successful() && $response->status() !== 500) {
             match ($response->status()) {
                 401 => throw new ConnectionFailed('Unauthorized. Please check the credentials.'),
                 403 => throw new ConnectionFailed('Unauthorized. You do not have access to this resource.'),
                 405 => throw new ConnectionFailed('Command does not exist.'),
-                default => throw new ConnectionFailed('Something went wrong.'),
+                default => throw new ConnectionFailed('Something went wrong: '.$response->body()),
             };
         }
 
         try {
-            $content = json_decode($response->body(), associative: true, flags: JSON_THROW_ON_ERROR);
+            $result = json_decode($response->body(), associative: true, flags: JSON_THROW_ON_ERROR);
+            $result = collect($result);
         } catch (JsonException) {
-            $content = collect(explode('&', urldecode($response->body())))
-                ->map(function ($item) {
-                    [$value, $key] = explode('=', $item);
+            throw new InvalidResponse('Invalid JSON returned by server: '.$response->body());
+        }
+
+        $this->validate($result);
+
+        return $result;
+    }
+
+    /**
+     * Validate the content returned by DirectAdmin. Even though the
+     * API can return a successfull response to our HTTP-request
+     * the actual call may have failed.
+     *
+     * @throws InvalidResponse
+     */
+    protected function validate(Collection $result): void
+    {
+        if ($result->has('error')) {
+            $error = $result->get('error');
+            $description = $result->get('result');
 
-                    return [$key => $value];
-                })
-                ->toArray();
+            if (! empty($description)) {
+                $description = ': '.$description;
+            }
+
+            throw new InvalidResponse($error.$description);
         }
+    }
 
-        return $content;
+    protected function getHttpOptions(): array
+    {
+        return [
+            'debug' => $this->debug,
+        ];
+    }
+
+    protected function getQueryParams(): array
+    {
+        return [
+            'json' => 'yes',
+        ];
     }
 
     /**
      * @throws ConnectionFailed
+     * @throws InvalidResponse
      */
     public function __call(string $name, array $arguments)
     {

src/DirectAdmin.php

@@ -2,9 +2,11 @@
 
 namespace Sensson\DirectAdmin;
 
+use Illuminate\Support\Collection;
 use Illuminate\Support\Traits\ForwardsCalls;
 use Illuminate\Support\Traits\Tappable;
 use Sensson\DirectAdmin\Exceptions\ConnectionFailed;
+use Sensson\DirectAdmin\Exceptions\InvalidResponse;
 
 class DirectAdmin
 {
@@ -18,8 +20,9 @@ public function __construct(public Api $api)
 
     /**
      * @throws ConnectionFailed
+     * @throws InvalidResponse
      */
-    public function call(string $command, array $params = []): array
+    public function call(string $command, array $params = []): Collection
     {
         return $this->api->call($command, $params);
     }

src/Exceptions/InvalidResponse.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Sensson\DirectAdmin\Exceptions;
+
+use Exception;
+
+class InvalidResponse extends Exception
+{
+    //
+}

src/Facades/DirectAdmin.php

@@ -8,7 +8,8 @@
 /**
  * @see BaseDirectAdmin
  *
- * @method static call(string $string)
+ * @method static call(string $string, array $params = [])
+ * @method static debug()
  */
 class DirectAdmin extends Facade
 {