Full API

.gitignore

@@ -1,2 +1,3 @@
 /vendor/
 /composer.lock
+/.phpunit.result.cache

composer.json

@@ -18,8 +18,7 @@
   ],
   "require": {
     "php": ">=8.0.0",
-    "ext-curl": "*",
-    "ext-json": "*"
+    "ext-curl": "*"
   },
   "autoload": {
     "psr-4": { "Pushpad\\" : "lib/" }

init.php

@@ -1,4 +1,13 @@
 <?php
 
-require(dirname(__FILE__) . '/lib/Pushpad.php');
-require(dirname(__FILE__) . '/lib/Notification.php');
+require dirname(__FILE__) . '/lib/Exception/PushpadException.php';
+require dirname(__FILE__) . '/lib/Exception/ConfigurationException.php';
+require dirname(__FILE__) . '/lib/Exception/ApiException.php';
+require dirname(__FILE__) . '/lib/Exception/NetworkException.php';
+require dirname(__FILE__) . '/lib/Pushpad.php';
+require dirname(__FILE__) . '/lib/Resource.php';
+require dirname(__FILE__) . '/lib/HttpClient.php';
+require dirname(__FILE__) . '/lib/Notification.php';
+require dirname(__FILE__) . '/lib/Subscription.php';
+require dirname(__FILE__) . '/lib/Project.php';
+require dirname(__FILE__) . '/lib/Sender.php';

lib/Exception/ApiException.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pushpad\Exception;
+
+/**
+ * Represents an error response returned by the Pushpad API.
+ */
+class ApiException extends PushpadException
+{
+    private int $statusCode;
+
+    /** @var mixed */
+    private $responseBody;
+
+    /**
+     * @var array<string, array<int, string>>|null
+     */
+    private ?array $responseHeaders;
+
+    private ?string $rawBody;
+
+    /**
+     * @param mixed $responseBody
+     * @param array<string, array<int, string>>|null $responseHeaders
+     */
+    public function __construct(
+        string $message,
+        int $statusCode,
+        $responseBody = null,
+        ?array $responseHeaders = null,
+        ?string $rawBody = null
+    ) {
+        parent::__construct($message, $statusCode);
+
+        $this->statusCode = $statusCode;
+        $this->responseBody = $responseBody;
+        $this->responseHeaders = $responseHeaders;
+        $this->rawBody = $rawBody;
+    }
+
+    public function getStatusCode(): int
+    {
+        return $this->statusCode;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getResponseBody()
+    {
+        return $this->responseBody;
+    }
+
+    /**
+     * @return array<string, array<int, string>>|null
+     */
+    public function getResponseHeaders(): ?array
+    {
+        return $this->responseHeaders;
+    }
+
+    public function getRawBody(): ?string
+    {
+        return $this->rawBody;
+    }
+
+    /**
+     * @param array{status?:int, body?:mixed, headers?:array<string, array<int, string>>, raw_body?:?string} $response
+     */
+    public static function fromResponse(array $response): self
+    {
+        $status = isset($response['status']) ? (int) $response['status'] : 0;
+        $body = $response['body'] ?? null;
+        $headers = $response['headers'] ?? null;
+        $rawBody = $response['raw_body'] ?? null;
+
+        $message = self::buildMessage($status, $body);
+
+        return new self($message, $status, $body, $headers, $rawBody);
+    }
+
+    /**
+     * @param mixed $body
+     */
+    private static function buildMessage(int $status, $body): string
+    {
+        $baseMessage = sprintf('Pushpad API responded with status %d.', $status);
+
+        $details = '';
+
+        if (is_array($body)) {
+            foreach (['error_description', 'error', 'message'] as $key) {
+                if (isset($body[$key]) && is_scalar($body[$key])) {
+                    $details = (string) $body[$key];
+                    break;
+                }
+            }
+
+            if ($details === '' && isset($body['errors'])) {
+                $encoded = json_encode($body['errors']);
+                $details = $encoded !== false ? $encoded : '';
+            }
+        } elseif (is_scalar($body) && $body !== '') {
+            $details = (string) $body;
+        }
+
+        if ($details === '' && $body !== null) {
+            $encoded = json_encode($body);
+            $details = $encoded !== false ? $encoded : '';
+        }
+
+        if ($details === '' || $details === 'null') {
+            return $baseMessage;
+        }
+
+        return $baseMessage . ' ' . $details;
+    }
+}

lib/Exception/ConfigurationException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pushpad\Exception;
+
+/**
+ * Raised when the SDK is misconfigured.
+ */
+class ConfigurationException extends PushpadException
+{
+}
+

lib/Exception/NetworkException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pushpad\Exception;
+
+/**
+ * Raised when an HTTP request cannot be completed due to network errors.
+ */
+class NetworkException extends PushpadException
+{
+}

lib/Exception/PushpadException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pushpad\Exception;
+
+use RuntimeException;
+
+/**
+ * Base exception for all Pushpad SDK specific errors.
+ */
+class PushpadException extends RuntimeException
+{
+}
+

lib/HttpClient.php

@@ -0,0 +1,204 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pushpad;
+
+use Pushpad\Exception\NetworkException;
+
+/**
+ * Thin wrapper around cURL tailored to the Pushpad API conventions.
+ */
+class HttpClient
+{
+    private string $baseUrl;
+    private string $authToken;
+    private int $timeout;
+    private string $userAgent;
+
+    /**
+     * Initializes the HTTP client with some options.
+     *
+     * @param string $authToken API token granted by Pushpad.
+     * @param string $baseUrl Base endpoint for the REST API.
+     * @param int $timeout Default timeout in seconds for requests.
+     * @param string $userAgent Forces a custom User-Agent header when provided.
+     *
+     * @throws \InvalidArgumentException When the authentication token is empty.
+     */
+    public function __construct(string $authToken, string $baseUrl = 'https://pushpad.xyz/api/v1', int $timeout = 30, string $userAgent = 'pushpad-php')
+    {
+        if ($authToken === '') {
+            throw new \InvalidArgumentException('Auth token must be a non-empty string.');
+        }
+
+        $this->authToken = $authToken;
+        $this->baseUrl = rtrim($baseUrl, '/');
+        $this->timeout = $timeout;
+        $this->userAgent = $userAgent;
+    }
+
+    /**
+     * Executes an HTTP request against the Pushpad API.
+     *
+     * @param string $method HTTP verb used for the request.
+     * @param string $path Relative path appended to the base URL.
+     * @param array{query?:array<string,mixed>, json?:mixed, body?:string, headers?:array<int,string>, timeout?:int} $options
+     * @return array{status:int, body:mixed, headers:array<string, array<int, string>>, raw_body:?string}
+     *
+     * @throws NetworkException When the underlying cURL call fails.
+     * @throws \RuntimeException When encoding the JSON payload fails.
+     */
+    public function request(string $method, string $path, array $options = []): array
+    {
+        $url = $this->buildUrl($path, $options['query'] ?? []);
+        $payload = null;
+        $headers = $this->defaultHeaders();
+
+        if (isset($options['json'])) {
+            $payload = json_encode($options['json']);
+            if ($payload === false) {
+                throw new \RuntimeException('Failed to encode JSON payload.');
+            }
+            $headers[] = 'Content-Type: application/json';
+        } elseif (isset($options['body'])) {
+            $payload = (string) $options['body'];
+        }
+
+        if (!empty($options['headers'])) {
+            $headers = array_merge($headers, $options['headers']);
+        }
+
+        $timeout = isset($options['timeout']) ? (int) $options['timeout'] : $this->timeout;
+
+        $responseHeaders = [];
+        $handle = curl_init($url);
+        if ($handle === false) {
+            throw new NetworkException('Unable to initialize cURL.');
+        }
+
+        curl_setopt($handle, CURLOPT_CUSTOMREQUEST, strtoupper($method));
+        curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
+        curl_setopt($handle, CURLOPT_TIMEOUT, $timeout);
+        curl_setopt($handle, CURLOPT_HTTPHEADER, $headers);
+        curl_setopt($handle, CURLOPT_USERAGENT, $this->userAgent);
+        curl_setopt($handle, CURLOPT_FOLLOWLOCATION, false);
+        curl_setopt($handle, CURLOPT_HEADER, false);
+        curl_setopt($handle, CURLOPT_HEADERFUNCTION, function ($curl, string $line) use (&$responseHeaders): int {
+            $trimmed = trim($line);
+            if ($trimmed === '' || stripos($trimmed, 'HTTP/') === 0) {
+                return strlen($line);
+            }
+            [$name, $value] = array_map('trim', explode(':', $trimmed, 2));
+            $key = strtolower($name);
+            $responseHeaders[$key] = $responseHeaders[$key] ?? [];
+            $responseHeaders[$key][] = $value;
+            return strlen($line);
+        });
+
+        if ($payload !== null) {
+            curl_setopt($handle, CURLOPT_POSTFIELDS, $payload);
+        }
+
+        $rawBody = curl_exec($handle);
+        if ($rawBody === false) {
+            $errorMessage = curl_error($handle);
+            curl_close($handle);
+            throw new NetworkException('cURL request error: ' . $errorMessage);
+        }
+
+        $status = (int) curl_getinfo($handle, CURLINFO_HTTP_CODE);
+        curl_close($handle);
+
+        return [
+            'status' => $status,
+            'body' => $this->decode($rawBody),
+            'headers' => $responseHeaders,
+            'raw_body' => $rawBody === '' ? null : $rawBody,
+        ];
+    }
+
+    /**
+     * Produces the base headers required for API requests.
+     *
+     * @return list<string>
+     */
+    private function defaultHeaders(): array
+    {
+        return [
+            'Authorization: Bearer ' . $this->authToken,
+            'Accept: application/json',
+        ];
+    }
+
+    /**
+     * Creates an absolute URL including any query string parameters.
+     *
+     * @param string $path Request path relative to the base URL.
+     * @param array<string, mixed> $query
+     * @return string
+     */
+    private function buildUrl(string $path, array $query): string
+    {
+        $url = $this->baseUrl . '/' . ltrim($path, '/');
+        if (!empty($query)) {
+            $queryString = $this->buildQueryString($query);
+            if ($queryString !== '') {
+                $url .= '?' . $queryString;
+            }
+        }
+
+        return $url;
+    }
+
+    /**
+     * Builds a URL-encoded query string from the provided parameters.
+     *
+     * @param array<string, mixed> $query
+     * @return string
+     */
+    private function buildQueryString(array $query): string
+    {
+        $parts = [];
+        foreach ($query as $key => $value) {
+            if ($value === null) {
+                continue;
+            }
+
+            if (is_array($value)) {
+                foreach ($value as $item) {
+                    if ($item === null) {
+                        continue;
+                    }
+                    $parts[] = rawurlencode($key . '[]') . '=' . rawurlencode((string) $item);
+                }
+                continue;
+            }
+
+            $parts[] = rawurlencode((string) $key) . '=' . rawurlencode((string) $value);
+        }
+
+        return implode('&', $parts);
+    }
+
+    /**
+     * Decodes the JSON body when possible, returning the raw string otherwise.
+     *
+     * @param string $rawBody Raw body returned by cURL.
+     * @return mixed
+     */
+    private function decode(string $rawBody)
+    {
+        $trimmed = trim($rawBody);
+        if ($trimmed === '') {
+            return null;
+        }
+
+        $decoded = json_decode($trimmed, true);
+        if (json_last_error() === JSON_ERROR_NONE) {
+            return $decoded;
+        }
+
+        return $trimmed;
+    }
+}