README

PHP client library for communication with ATK14 RESTful APIs and other JSON APIs.

• Installation
• Basic usage
• HTTP methods
• Sending files and raw data
• Error handling
• Inspecting the response
• Language
• HTTP Basic Authentication
• Additional headers
• Caching
• Proxy
• SSL verification
• Timeout
• Constructor options reference
• Tracy panel integration
• License

Installation

composer require atk14/api-data-fetcher

Optionally, set the default base URL in your project configuration:

define("API_DATA_FETCHER_BASE_URL", "https://api.example.com/api/");

Basic usage

$adf = new ApiDataFetcher("https://api.example.com/api/");

$data = $adf->get("articles/detail", ["id" => 123]);
// Calls: GET https://api.example.com/api/en/articles/detail/?id=123&format=json

echo $data["title"];

Parameters can also be embedded directly in the action string:

$data = $adf->get("articles/detail/?id=123");

Array parameters are serialized automatically:

$data = $adf->get("articles/index", ["tags" => ["php", "api"]]);
// Calls: ...?tags[]=php&tags[]=api&format=json

The lang segment and format=json parameter are added automatically on every request. See Language and Constructor options reference to configure or disable this behaviour.

HTTP methods

$data = $adf->get("articles/detail",    ["id" => 123]);
$data = $adf->post("articles/create",   ["title" => "Hello", "body" => "..."]);
$data = $adf->put("articles/update",    ["id" => 123, "title" => "Hello 2"]);
$data = $adf->delete("articles/delete", ["id" => 123]);

Sending files and raw data

File upload

// Simple form — just pass a path
$data = $adf->postFile("images/create", "/path/to/image.jpg", ["title" => "Flower"]);

// Full control over file metadata
$data = $adf->postFile("images/create", [
    "path"      => "/path/to/image.jpg",
    "name"      => "flower.jpg",       // filename sent to the server
    "mime_type" => "image/jpeg",        // auto-detected when omitted
], ["title" => "Flower"]);

Posting JSON

// Pass an array — it is encoded automatically
$data = $adf->postJson("articles/import", ["title" => "Hello", "body" => "..."]);

// Or pass a pre-encoded string
$data = $adf->postJson("articles/import", '{"title":"Hello"}');

// URL parameters alongside the JSON body
$data = $adf->postJson("articles/import", $payload, ["params" => ["lang" => "en"]]);

Posting raw data

$data = $adf->postRawData("endpoint", $binary_content, [], ["mime_type" => "application/octet-stream"]);

Error handling

By default, any non-2xx response throws an exception. The exception hierarchy is:

All four extend ApiDataFetcher\Exception.

Catching exceptions

try {
    $data = $adf->get("articles/detail", ["id" => 999]);
} catch (ApiDataFetcher\HttpException $e) {
    echo $e->getStatusCode();  // e.g. 404
    echo $e->getContent();     // raw response body
    echo $e->getHeaders();     // raw response headers
} catch (ApiDataFetcher\NetworkException $e) {
    echo "Connection failed: " . $e->getMessage();
}

Acceptable error codes

To handle specific error responses as valid (non-exceptional) results, list them in acceptable_error_codes. The method then returns null instead of throwing.

$data = $adf->post("logins/create", [
    "login"    => "johny",
    "password" => "secret",
], [
    "acceptable_error_codes" => [401, 404],
]);

if (!$data) {
    if ($adf->getStatusCode() == 401) { /* bad password */ }
    if ($adf->getStatusCode() == 404) { /* user not found */ }
}

Inspecting the response

These methods are available after every request:

$adf->getStatusCode();    // int,    e.g. 200, 201, 404
$adf->getStatusMessage(); // string, e.g. "OK", "Created", "Not Found"
$adf->getRawResponse();   // string, raw response body
$adf->getUrl();           // string, full URL that was called
$adf->getMethod();        // string, "GET", "POST", "PUT", "DELETE"
$adf->getDuration();      // float,  request duration in seconds
$adf->isResponseCached(); // bool,   true when the response came from cache
$adf->getErrors();        // array,  error payload on non-2xx responses

Returning raw content

To skip JSON decoding and get the raw response string directly:

$html = $adf->get("pages/export", ["id" => 5], ["return_raw_content" => true]);

Language

ApiDataFetcher automatically inserts the current application language into every URL (e.g. .../en/...). The language is detected from the ATK14 framework; it defaults to "en" outside ATK14.

// Set language globally in the constructor
$adf = new ApiDataFetcher("https://api.example.com/api/", ["lang" => "cs"]);

// Override per request
$data = $adf->get("articles/detail", ["id" => 123, "lang" => "de"]);

// Disable language segment entirely (for non-ATK14 APIs)
$adf = new ApiDataFetcher("https://external-api.com/v1/", ["lang" => ""]);

HTTP Basic Authentication

Embed credentials directly in the base URL. Passwords are never written to logs.

$adf = new ApiDataFetcher("https://user:password@api.example.com/api/");

Additional headers

// Set headers for all requests
$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "additional_headers" => [
        "X-Forwarded-For: 1.2.3.4",
        "Authorization: Bearer " . $token,
    ],
]);

// Or set headers for a single request
$data = $adf->get("articles/detail", ["id" => 123], [
    "additional_headers" => ["X-Request-Id: abc123"],
]);

If the same header name appears in both the instance-level and the request-level list, the request-level value wins (case-insensitive matching).

Caching

Responses can be cached to a local file. Pass the TTL in seconds:

// Cache for 10 minutes
$data = $adf->get("articles/index", ["year" => 2025], ["cache" => 600]);

// Fall back to an expired cache entry when a live request fails
$data = $adf->get("articles/index", ["year" => 2025], [
    "cache"                       => 600,
    "return_cached_content_on_error" => true,
]);

By default, cache files are stored in the system temp directory. Pass a custom CacheFileStorage instance to change the location:

$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "cache_storage" => new CacheFileStorage("/var/cache/my-app"),
]);

CacheFileStorage can also be used independently:

$cache = new CacheFileStorage("/var/cache/my-app");
$cache->write("key", $data, 300); // expires in 5 minutes
$data = $cache->read("key");      // returns null when expired or missing

Proxy

$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "proxy" => "tcp://proxy.example.com:8118",
]);

SSL verification

// Disable peer name verification (e.g. when the certificate covers a different hostname)
$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "verify_peer_name" => false,
]);

// Disable certificate verification entirely (not recommended in production)
$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "verify_peer" => false,
]);

Timeout

Set the socket timeout in the constructor or change it at any time:

$adf = new ApiDataFetcher("https://api.example.com/api/", [
    "socket_timeout" => 10.0, // seconds, default is 5.0
]);

// Change timeout temporarily and restore afterwards
$previous = $adf->setSocketTimeout(30.0);
$data = $adf->get("reports/generate");
$adf->setSocketTimeout($previous);

Constructor options reference

Tracy panel integration

The package ships with ApiDataFetcherPanel for the Tracy debugger. It shows the number of API calls and their details in the debug bar.

$bar = Tracy\Debugger::getBar();
$bar->addPanel(new ApiDataFetcherPanel($adf));

// Custom panel title when multiple APIs are used
$bar->addPanel(new ApiDataFetcherPanel($adf, ["title" => "Products API"]));

License

ApiDataFetcher is free software distributed under the terms of the MIT license.