feat: Implements the SDK for HamroCDN

README.md

@@ -1 +1,4 @@
 # HamroCDN PHP SDK
+
+[![Lint & Test PR](https://github.com/HamroCDN/php-sdk/actions/workflows/prlint.yml/badge.svg)](https://github.com/HamroCDN/php-sdk/actions/workflows/prlint.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=HamroCDN_php-sdk&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=HamroCDN_php-sdk)

composer.json

@@ -23,13 +23,6 @@
             "HamroCDN\\Tests\\": "tests/"
         }
     },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "HamroCDN\\Laravel\\HamroCDNServiceProvider"
-            ]
-        }
-    },
     "authors": [
         {
             "name": "achyutkneupane",
@@ -39,7 +32,8 @@
         }
     ],
     "require": {
-        "php": ">=8.0"
+        "php": ">=8.0",
+        "guzzlehttp/guzzle": "^7.10"
     },
     "require-dev": {
         "laravel/pint": "^1.25",

rector.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Rector\Config\RectorConfig;
+use Rector\DeadCode\Rector\Node\RemoveNonExistingVarAnnotationRector;
 
 try {
     return RectorConfig::configure()
@@ -16,6 +17,9 @@
             privatization: true,
             earlyReturn: true,
         )
+        ->withSkip([
+            RemoveNonExistingVarAnnotationRector::class,
+        ])
         ->withPhpSets(
             php84: true,
         );

src/Contracts/HamroCDNContract.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HamroCDN\Contracts;
+
+/**
+ * @phpstan-type HamroCDNFile array{
+ *     url: string,
+ *     size: int
+ * }
+ * @phpstan-type HamroCDNUser array{
+ *     name: string,
+ *     email: string,
+ *     role: string
+ * }
+ * @phpstan-type HamroCDNObject array{
+ *     nanoId: string,
+ *     user: HamroCDNUser,
+ *     delete_at: string|null,
+ *     original: HamroCDNFile
+ * }
+ * @phpstan-type HamroCDNData array{
+ *     data: HamroCDNObject
+ * }
+ * @phpstan-type HamroCDNObjectWithPagination array{
+ *     data: array<HamroCDNObject>,
+ *     meta: array{total: int, per_page: int, page: int}
+ * }
+ */
+interface HamroCDNContract
+{
+    /**
+     * List all of your files in HamroCDN.
+     *
+     * @return HamroCDNObjectWithPagination
+     */
+    public function index(): array;
+
+    /**
+     * Fetch a file from HamroCDN.
+     *
+     * @return HamroCDNData
+     */
+    public function fetch(string $nanoId): array;
+
+    /**
+     * Upload a file to HamroCDN.
+     *
+     * @return HamroCDNData
+     */
+    public function upload(string $filePath): array;
+
+    /**
+     * Upload a file to HamroCDN by URL.
+     *
+     * @return HamroCDNData
+     */
+    public function uploadByURL(string $url): array;
+}

src/Exceptions/HamroCDNException.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HamroCDN\Exceptions;
+
+use Exception;
+use Throwable;
+
+/**
+ * Base exception for all HamroCDN SDK errors.
+ *
+ * @api
+ */
+final class HamroCDNException extends Exception
+{
+    public function __construct(string $message = 'An error occurred with HamroCDN.', int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * Factory for network or Guzzle-related errors.
+     */
+    public static function networkError(Throwable $previous): self
+    {
+        return new self('Network error while communicating with HamroCDN.', 1001, $previous);
+    }
+
+    /**
+     * Factory for invalid or non-JSON API responses.
+     */
+    public static function invalidResponse(?string $response = null): self
+    {
+        $msg = 'Invalid JSON returned by HamroCDN API.';
+        if ($response !== null) {
+            $msg .= ' Response: '.mb_substr($response, 0, 200).'...';
+        }
+
+        return new self($msg, 1002);
+    }
+
+    /**
+     * Factory for invalid local file operations.
+     */
+    public static function fileError(string $path): self
+    {
+        return new self("File not found or unreadable: {$path}", 1004);
+    }
+}

src/HamroCDN.php

@@ -4,7 +4,89 @@
 
 namespace HamroCDN;
 
-final class HamroCDN
+use GuzzleHttp\Client;
+use HamroCDN\Contracts\HamroCDNContract;
+use HamroCDN\Exceptions\HamroCDNException;
+use HamroCDN\Traits\HasConfigValues;
+use HamroCDN\Traits\Requestable;
+
+/**
+ * @phpstan-import-type HamroCDNData from HamroCDNContract
+ * @phpstan-import-type HamroCDNObjectWithPagination from HamroCDNContract
+ */
+final class HamroCDN implements HamroCDNContract
 {
-    //
+    /**
+     * @use Requestable<HamroCDNData>
+     */
+    use HasConfigValues, Requestable;
+
+    public function __construct(?string $apiKey = null, ?string $baseUrl = null, ?Client $client = null)
+    {
+        [$this->apiKey, $this->baseUrl] = $this->resolveConfig($apiKey, $baseUrl);
+
+        $this->client = $client ?? new Client([
+            'base_uri' => "{$this->baseUrl}/",
+            'timeout' => 15,
+            'verify' => true,
+            'headers' => [
+                'X-API-KEY' => $this->apiKey,
+                'Accept' => 'application/json',
+            ],
+        ]);
+    }
+
+    /**
+     * @return HamroCDNObjectWithPagination
+     *
+     * @throws HamroCDNException
+     */
+    public function index(?int $per_page = 20, ?int $page = 1): array
+    {
+        /** @var HamroCDNObjectWithPagination */
+        return $this->get('uploads', [
+            'per_page' => $per_page,
+            'page' => $page,
+        ]);
+    }
+
+    /**
+     * @throws HamroCDNException
+     */
+    public function fetch(string $nanoId): array
+    {
+        return $this->get("uploads/{$nanoId}");
+    }
+
+    /**
+     * @throws HamroCDNException
+     */
+    public function upload(string $filePath): array
+    {
+        if (! file_exists($filePath)) {
+            throw HamroCDNException::fileError($filePath);
+        }
+
+        return $this->post('uploads', [
+            'multipart' => [
+                [
+                    'name' => 'file',
+                    'contents' => fopen($filePath, 'r'),
+                    'filename' => basename($filePath),
+                ],
+            ],
+        ]);
+    }
+
+    /**
+     * @throws HamroCDNException
+     */
+    public function uploadByURL(string $url): array
+    {
+        return $this->post('upload-from-url', [
+            'json' => [
+                'url' => $url,
+            ],
+        ]);
+    }
 }

src/Traits/HasConfigValues.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HamroCDN\Traits;
+
+use HamroCDN\Exceptions\HamroCDNException;
+
+trait HasConfigValues
+{
+    protected ?string $apiKey;
+
+    protected string $baseUrl;
+
+    /**
+     * Resolve API key and base URL from multiple sources.
+     *
+     * @return array{string, string} [apiKey, baseUrl]
+     *
+     * @throws HamroCDNException
+     */
+    protected function resolveConfig(?string $apiKey = null, ?string $baseUrl = null): array
+    {
+        $defaultURL = 'https://hamrocdn.com/api';
+
+        $this->apiKey = $this->stringOrNull($apiKey)
+            ?? $this->getConfigValue('hamrocdn.api_key')
+            ?? $this->getEnvValue('HAMROCDN_API_KEY');
+
+        $this->baseUrl = rtrim(
+            $baseUrl
+            ?? $this->getConfigValue('hamrocdn.api_url')
+            ?? $this->getEnvValue('HAMROCDN_API_URL')
+            ?? $defaultURL,
+            '/'
+        );
+
+        if (empty($this->apiKey)) {
+            throw new HamroCDNException('API key is required for HamroCDN client.');
+        }
+
+        return [$this->apiKey, $this->baseUrl];
+    }
+
+    /**
+     * Retrieve a configuration value if the helper exists.
+     */
+    private function getConfigValue(string $key): ?string
+    {
+        /** @var string|null */
+        return function_exists('config') ? config($key) : null;
+    }
+
+    /**
+     * Retrieve a environment variable if the helper exists.
+     */
+    private function getEnvValue(string $key): ?string
+    {
+        return $this->stringOrNull(
+            function_exists('env') ? getenv($key) : null
+        );
+    }
+
+    /**
+     * Convert false|string|null into nullable string.
+     */
+    private function stringOrNull(string|false|null $value): ?string
+    {
+        return is_string($value) && $value !== '' ? $value : null;
+    }
+}

src/Traits/Requestable.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HamroCDN\Traits;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\Exception\GuzzleException;
+use HamroCDN\Exceptions\HamroCDNException;
+use Throwable;
+
+/**
+ * @template T
+ */
+trait Requestable
+{
+    protected Client $client;
+
+    /**
+     * @param  array<string,mixed>  $query
+     * @return T
+     *
+     * @throws HamroCDNException
+     */
+    private function get(string $endpoint, array $query = []): array
+    {
+        try {
+            $response = $this->client->get($endpoint, ['query' => $query]);
+
+            return $this->decodeResponse($response->getBody()->getContents());
+        } catch (GuzzleException $e) {
+            throw HamroCDNException::networkError($e);
+        } catch (Throwable $e) {
+            throw new HamroCDNException('Unexpected error while performing GET request.', 1000, $e);
+        }
+    }
+
+    /**
+     * @param  array<string,mixed>  $options
+     * @return T
+     *
+     * @throws HamroCDNException
+     */
+    private function post(string $endpoint, array $options = []): array
+    {
+        try {
+            $response = $this->client->post($endpoint, $options);
+
+            return $this->decodeResponse($response->getBody()->getContents());
+        } catch (GuzzleException $e) {
+            throw HamroCDNException::networkError($e);
+        } catch (Throwable $e) {
+            throw new HamroCDNException('Unexpected error while performing POST request.', 1000, $e);
+        }
+    }
+
+    /**
+     * @return T
+     *
+     * @throws HamroCDNException
+     */
+    private function decodeResponse(string $json): array
+    {
+        /** @var T $decoded */
+        $decoded = json_decode($json, true);
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw HamroCDNException::invalidResponse('Invalid JSON returned by API.');
+        }
+
+        return $decoded;
+    }
+}