PHP

Calling Flares Cloud from PHP backends — and from Functions.

A client for backends

From a PHP backend (including inside a Flares Function, once outbound network access is enabled) the API is ordinary HTTP. This client is small enough to read in one sitting.

<?php

final class FlaresCloud
{
    public function __construct(
        private string $projectId,
        private string $key,                 // secret key for backends
        private string $baseUrl = 'https://cloud.flaresinc.com',
    ) {
    }

    /** @return array<string,mixed> */
    public function call(string $path, string $method = 'GET', ?array $body = null, ?string $userToken = null): array
    {
        $headers = ['Authorization: Bearer ' . $this->key];

        if ($body !== null) {
            $headers[] = 'Content-Type: application/json';
        }
        if ($userToken !== null) {
            $headers[] = 'X-Basket-User-Token: ' . $userToken;
        }

        $ch = curl_init($this->baseUrl . '/v1/projects/' . $this->projectId . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
            CURLOPT_TIMEOUT => 15,
        ]);

        $raw = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $decoded = json_decode((string) $raw, true) ?: [];

        if ($status >= 400) {
            throw new RuntimeException(($decoded['message'] ?? 'Request failed') . ' [' . ($decoded['error'] ?? $status) . ']', $status);
        }

        return $decoded;
    }

    // --- Basket ------------------------------------------------------------

    public function query(string $collection, array $query = [], ?string $userToken = null): array
    {
        $params = [];
        foreach (['where' => true, 'orderBy' => false, 'direction' => false, 'limit' => false, 'cursor' => false] as $k => $json) {
            if (isset($query[$k])) {
                $params[$k] = $json ? json_encode($query[$k]) : $query[$k];
            }
        }

        return $this->call('/collections/' . $collection . '/records?' . http_build_query($params), 'GET', null, $userToken);
    }

    public function createRecord(string $collection, array $data, ?string $userToken = null): array
    {
        return $this->call('/collections/' . $collection . '/records', 'POST', ['data' => $data], $userToken)['record'];
    }

    public function updateRecord(string $collection, string $id, array $data, ?int $version = null): array
    {
        return $this->call('/collections/' . $collection . '/records/' . $id, 'PATCH',
            ['data' => $data] + ($version === null ? [] : ['version' => $version]))['record'];
    }

    public function deleteRecord(string $collection, string $id): void
    {
        $this->call('/collections/' . $collection . '/records/' . $id, 'DELETE');
    }

    // --- Auth administration (secret key) -----------------------------------

    public function users(string $search = '', int $limit = 50): array
    {
        return $this->call('/auth/users?' . http_build_query(['search' => $search, 'limit' => $limit]))['users'];
    }

    public function createUser(string $email, ?string $password = null, bool $verified = false): array
    {
        return $this->call('/auth/users', 'POST', array_filter([
            'email' => $email, 'password' => $password, 'email_verified' => $verified,
        ], static fn ($v) => $v !== null))['user'];
    }

    public function disableUser(string $userId): array
    {
        return $this->call('/auth/users/' . $userId, 'PATCH', ['status' => 'disabled'])['user'];
    }

    public function revokeSessions(string $userId): int
    {
        return (int) $this->call('/auth/users/' . $userId . '/revoke-sessions', 'POST')['revoked_sessions'];
    }
}

Using it

$flares = new FlaresCloud('prj_…', getenv('FLARES_SECRET_KEY'));

$open = $flares->query('shipments', [
    'where' => [['status', '==', 'pending']],
    'orderBy' => 'created_at',
    'limit' => 100,
]);

$flares->createRecord('shipments', ['destination' => 'Kano', 'status' => 'pending']);
$flares->disableUser('usr_…');