1. class
  2. Core
  3. \
  4. Lib
  5. \
  6. Http
  7. \
  8. Api

Api

class Api

Lightweight HTTP JSON client with optional on-disk caching.

Responsibilities:

  • Build URLs from a base URL plus default and per-call query parameters.
  • Perform JSON-based GET/POST requests with cURL and sensible timeouts.
  • Cache successful GET responses to storage/cache/<namespace>/cache_<hash>.json.

Typical usage is to subclass this client and provide service-specific defaults (e.g., base URL, default headers, API key in $defaultQuery, TTL, etc.).

Constants

private CACHE_DIRECTORY

Root cache directory for the application.

Properties

protected string $baseUrl

Base URL (no trailing slash), e.g. "https://api.example.com/v1"
protected string $cacheDir

Absolute path to the cache directory for this client/namespace.
protected array<string,string> $defaultHeaders

Default headers sent on every request (merged with per-call headers).
protected array<string,mixed> $defaultQuery

Default query parameters merged into every request (per-call overrides).
protected int $defaultTtl

Default TTL (seconds) for GET cache. 0 disables caching.
protected int $timeout

Connection/overall timeout in seconds.

Methods

__construct(string $baseUrl, string $cacheNamespace = 'api', array $defaultHeaders = ['Accept' => 'application/json'], array $defaultQuery = [], int $defaultTtl = 0, int $timeout = 6)

Constructor for Api object.

string
buildUrl(string $path, array $query)

Build an absolute URL with merged default + per-call query parameters.

string
cacheFile(string $url)

Compute the cache filename for a given URL.

array
flattenHeaders(array $headers)

Convert an associative array of headers into "Key: Value" lines.

array
get(string $path, array $query = [], int|null $ttl = null)

Perform a GET request that expects a JSON response.

array
post(string $path, array $body = [], array $query = [], array $headers = [])

Perform a POST request with a JSON body and expect a JSON response.

array|null
readCache(string $url, int $ttl)

Read a cached JSON response for a URL if it exists and is fresh.

array
requestJson(string $method, string $url, string|null $body, array $headers)

Core HTTP request using cURL that decodes JSON and throws on errors.

void
writeCache(string $url, array $data)

Persist a decoded JSON response to the cache for a given URL.

Details

at line 72
__construct(string $baseUrl, string $cacheNamespace = 'api', array $defaultHeaders = ['Accept' => 'application/json'], array $defaultQuery = [], int $defaultTtl = 0, int $timeout = 6)

Constructor for Api object.

Parameters

string $baseUrl

Service base URL (e.g., "https://api.example.com")
string $cacheNamespace

Subdirectory under cache root (e.g., "api", "weather")
array $defaultHeaders

Default headers for all requests
array $defaultQuery

Default query params for all requests
int $defaultTtl

Default cache TTL (seconds) for GET; 0 disables caching
int $timeout

cURL timeout in seconds (also used as connect timeout)

at line 99
protected string buildUrl(string $path, array $query)

Build an absolute URL with merged default + per-call query parameters.

Per-call parameters override defaults on conflict.

Parameters

string $path

Path relative to the base URL (e.g., "/weather")
array $query

Per-call query parameters

Return Value

string

Absolute URL including query string

at line 111
protected string cacheFile(string $url)

Compute the cache filename for a given URL.

Parameters

string $url

Absolute URL

Return Value

string

Absolute path to the cache file

at line 121
protected array flattenHeaders(array $headers)

Convert an associative array of headers into "Key: Value" lines.

Parameters

array $headers

Return Value

array

at line 141
array get(string $path, array $query = [], int|null $ttl = null)

Perform a GET request that expects a JSON response.

Utilizes on-disk caching when TTL > 0.

Parameters

string $path

Path relative to base URL (e.g., "/weather")
array $query

Query parameters for this call
int|null $ttl

Override cache TTL (seconds); null uses default; 0 disables caching

Return Value

array

Decoded JSON as an associative array

Exceptions

APIException

at line 169
array post(string $path, array $body = [], array $query = [], array $headers = [])

Perform a POST request with a JSON body and expect a JSON response.

Parameters

string $path

Path relative to base URL
array $body

Payload to JSON-encode and send
array $query

Extra query parameters
array $headers

Extra headers (merged over defaults)

Return Value

array

Decoded JSON as an associative array

Exceptions

APIException

at line 188
protected array|null readCache(string $url, int $ttl)

Read a cached JSON response for a URL if it exists and is fresh.

Parameters

string $url

Absolute URL used as cache key
int $ttl

TTL in seconds

Return Value

array|null

Decoded JSON or null if cache miss/stale

at line 209
protected array requestJson(string $method, string $url, string|null $body, array $headers)

Core HTTP request using cURL that decodes JSON and throws on errors.

Parameters

string $method

HTTP method (e.g., "GET", "POST")
string $url

Absolute URL
string|null $body

Raw request body (e.g., JSON) or null
array $headers

Extra headers (merged over defaults)

Return Value

array

Decoded JSON as an associative array

Exceptions

APIException

at line 255
protected void writeCache(string $url, array $data)

Persist a decoded JSON response to the cache for a given URL.

Parameters

string $url

Absolute URL used as cache key
array $data

Decoded JSON to write

Return Value

void