README

OAuth2 client and request dispatcher for the Joy Pilot API tier.

Install

composer require greghanton/simplifi-hq-oauth-api

Configuration

This package loads defaults from config.php and then reads values from environment variables using simplifiHqOauthApiLibEnv().

Environment variables

Basic usage

Synchronous request

<?php

require __DIR__.'/vendor/autoload.php';

use SimplifiApi\ApiRequest;

$response = ApiRequest::request([
    'method' => 'GET',
    'url' => 'sales',
]);

if (! $response->success()) {
    throw new RuntimeException($response->errorsToString());
}

foreach ($response as $row) {
    // ApiResponse implements Iterator when response has a top-level "data" array.
    var_dump($row);
}

Async request

<?php

use SimplifiApi\ApiRequest;

$promise = ApiRequest::requestAsync([
    'method' => 'GET',
    'url' => 'sales',
]);

$response = $promise->wait();

if ($response->success()) {
    var_dump($response->response());
}

Batch request

<?php

use SimplifiApi\ApiRequest;

$responses = ApiRequest::batch([
    ['method' => 'GET', 'url' => 'sales'],
    ['method' => 'GET', 'url' => ['sales/$/invoice', 102]],
]);

foreach ($responses as $response) {
    if (! $response->success()) {
        error_log($response->errorsToString());
    }
}

Access token storage

Supported modes:

• custom (recommended for production; usually Redis)
• temp_file (unchanged local/dev fallback)

Redis setup via custom callables

SIMPLIFI_API_ACCESS_TOKEN_STORE_AS=custom
SIMPLIFI_API_ACCESS_TOKEN_CUSTOM_KEY=simplifi-hq-oauth-api-access-token
SIMPLIFI_API_ACCESS_TOKEN_GET="[\"\\\\App\\\\Cache\\\\TokenStore\", \"get\"]"
SIMPLIFI_API_ACCESS_TOKEN_SET="[\"\\\\App\\\\Cache\\\\TokenStore\", \"set\"]"
SIMPLIFI_API_ACCESS_TOKEN_DEL="[\"\\\\App\\\\Cache\\\\TokenStore\", \"del\"]"

Laravel example:

<?php

namespace App\Cache;

use Illuminate\Support\Facades\Cache;

class TokenStore
{
    public static function get(string $key): ?string
    {
        return Cache::store('redis')->get($key);
    }

    public static function set(string $key, string $value): bool
    {
        return Cache::store('redis')->forever($key, $value);
    }

    public static function del(string $key): bool
    {
        return Cache::store('redis')->forget($key);
    }
}

Token refresh mutex (optional, recommended in production)

When several processes see an expired token at the same time, configure lock/unlock callables to prevent duplicate oauth/token refresh requests.

SIMPLIFI_API_ACCESS_TOKEN_LOCK="[\"\\\\App\\\\Cache\\\\TokenLock\", \"acquire\"]"
SIMPLIFI_API_ACCESS_TOKEN_UNLOCK="[\"\\\\App\\\\Cache\\\\TokenLock\", \"release\"]"

Laravel lock example:

<?php

namespace App\Cache;

use Illuminate\Support\Facades\Cache;

class TokenLock
{
    private static array $locks = [];

    public static function acquire(string $customKey, int $ttl): bool
    {
        $lockName = $customKey.':oauth-refresh-lock';
        $lock = Cache::store('redis')->lock($lockName, $ttl);

        if (! $lock->get()) {
            return false;
        }

        self::$locks[$lockName] = $lock;

        return true;
    }

    public static function release(string $customKey): void
    {
        $lockName = $customKey.':oauth-refresh-lock';

        if (! isset(self::$locks[$lockName])) {
            return;
        }

        self::$locks[$lockName]->release();
        unset(self::$locks[$lockName]);
    }
}

Mutex flow inside the package:

1. Try to lock (currently with ~10s TTL).
2. If lock is acquired, refresh token and unlock.
3. If lock is not acquired, wait 1-2s, re-check cache, and reuse token if present.
4. Only fetch a fresh token if cache is still empty after waiting.

Event listener examples

Use listeners for metrics, tracing, or debugging without changing package internals.

<?php

use SimplifiApi\ApiRequest;
use SimplifiApi\ApiResponse;

ApiRequest::addEventListener(ApiRequest::EVENT_BEFORE_REQUEST, function (array $requestOptions, array $config): void {
    // Example: emit request-start metric.
});

ApiRequest::addEventListener(ApiRequest::EVENT_AFTER_REGULAR_REQUEST, function (ApiResponse $response): void {
    // Example: emit sync request timing metric.
});

ApiRequest::addEventListener(ApiRequest::EVENT_AFTER_ASYNC_REQUEST, function (ApiResponse $response): void {
    // Example: emit async request metric.
});

ApiRequest::addEventListener(ApiRequest::EVENT_AFTER_BATCH_REQUEST, function (ApiResponse $response): void {
    // Example: emit per-item batch metric.
});

ApiResponse::addEventListener(ApiResponse::EVENT_RESPONSE_CREATED, function (ApiResponse $response): void {
    // Example: central hook after any response object is created.
});

Laravel config:cache gotcha

src/helpers.php resolves env values in this order:

1. simplifiHqOauthApiEnv($key, $default) if your app defines it
2. fallback to Laravel env($key, $default) if available
3. fallback default

With Laravel config:cache, runtime env() calls outside config files return null. To keep custom token store and mutex callables reliable under cached config, define simplifiHqOauthApiEnv() in your app and read from your own config layer instead of direct runtime env().

Per-consumer grant matrix

The API tier's identity model (Stage 1.5) draws a hard line between three kinds of token, and this package only ever mints one of them. Use this table to decide how each consumer should be configured:

User-scoped tokens: the package never mints them

Per the Stage 1.5 identity model, the GUI/consumer owns acquiring and refreshing user-scoped tokens; this package only owns using them. Concretely:

1. At login, the consumer exchanges its one-time login token for a user-scoped access + refresh token pair directly against /oauth/token (grant_type=login_token), outside this package.
2. The consumer writes that token into a per-session custom store — i.e. a custom_key that is unique per user session, not the shared service-token key — using the same get/set/del callable hooks described above (Redis setup).
3. The consumer calls ApiRequest::request($options, $overrideConfig) with $overrideConfig pointing access_token.custom.custom_key (and get/set/del) at that per-session store.
4. $overrideConfig must also set 'allow_service_credential_mint' => false.

That last step matters: without it, if the per-session cache entry is missing or expired (token revoked, refresh not yet run, cache evicted), AccessToken::generateNewAccessToken() would fall through to minting a service (client_credentials) token from the global client_id/client_secret — and cache it under that user's session key. The next request would then silently run as the service account while believing it was acting as that user — exactly the identity-laundering hole the Stage 1.5 model closes. With allow_service_credential_mint=false set, a cache miss on a user-context config fails closed instead: ApiRequest::request() returns a non-success ApiResponse (no HTTP call is made), and the consumer should re-authenticate or run its own refresh flow rather than receive a token at all.

<?php

use SimplifiApi\ApiRequest;

// Per-session config for an authenticated user — set once after login/refresh writes the
// token into Redis under $sessionCustomKey.
$response = ApiRequest::request(
    ['method' => 'GET', 'url' => 'sales'],
    [
        'access_token' => [
            'store_as' => 'custom',
            'custom' => [
                'custom_key' => $sessionCustomKey,
                'get' => ['App\\Cache\\TokenStore', 'get'],
                'set' => ['App\\Cache\\TokenStore', 'set'],
                'del' => ['App\\Cache\\TokenStore', 'del'],
            ],
        ],
        'allow_service_credential_mint' => false,
    ]
);

Leave allow_service_credential_mint unset (defaults true) on the global/anonymous config used for client_credentials calls — there is no user identity to protect there, and that path is exactly what generateNewAccessToken() is for.

Development

composer run lint:check
composer run stan
composer run test

Docs

• Modernisation plan
• Stage 1.5 — Identity & Scopes (cross-repo source of truth)