PHPackages                             atk14/api-data-fetcher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. atk14/api-data-fetcher

ActiveLibrary[API Development](/categories/api)

atk14/api-data-fetcher
======================

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

v1.13.4(1w ago)047.6k↓41.3%3MITPHPPHP >=5.6.0CI passing

Since Sep 15Pushed 1w ago2 watchersCompare

[ Source](https://github.com/atk14/ApiDataFetcher)[ Packagist](https://packagist.org/packages/atk14/api-data-fetcher)[ Docs](https://github.com/atk14/ApiDataFetcher)[ RSS](/packages/atk14-api-data-fetcher/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (16)Versions (53)Used By (3)

ApiDataFetcher
==============

[](#apidatafetcher)

[![Tests](https://github.com/atk14/ApiDataFetcher/actions/workflows/tests.yml/badge.svg)](https://github.com/atk14/ApiDataFetcher/actions/workflows/tests.yml)

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

- [Installation](#installation)
- [Basic usage](#basic-usage)
- [HTTP methods](#http-methods)
- [Sending files and raw data](#sending-files-and-raw-data)
- [Error handling](#error-handling)
- [Inspecting the response](#inspecting-the-response)
- [Language](#language)
- [HTTP Basic Authentication](#http-basic-authentication)
- [Additional headers](#additional-headers)
- [Caching](#caching)
- [Proxy](#proxy)
- [SSL verification](#ssl-verification)
- [Timeout](#timeout)
- [Constructor options reference](#constructor-options-reference)
- [Tracy panel integration](#tracy-panel-integration)
- [License](#license)

Installation
------------

[](#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
-----------

[](#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](#language) and [Constructor options reference](#constructor-options-reference) to configure or disable this behaviour.

HTTP methods
------------

[](#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
--------------------------

[](#sending-files-and-raw-data)

### File upload

[](#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

[](#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

[](#posting-raw-data)

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

```

Error handling
--------------

[](#error-handling)

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

ExceptionThrown when`ApiDataFetcher\HttpException`Server returned a non-2xx HTTP status code`ApiDataFetcher\NetworkException`Connection failed (DNS failure, timeout, …)`ApiDataFetcher\NoContentException`Response body is empty (and status is not 204)`ApiDataFetcher\InvalidContentException`Response body is not valid JSONAll four extend `ApiDataFetcher\Exception`.

### Catching exceptions

[](#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

[](#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
-----------------------

[](#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

[](#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
--------

[](#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
-------------------------

[](#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
------------------

[](#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
-------

[](#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
-----

[](#proxy)

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

```

SSL verification
----------------

[](#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
-------

[](#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
-----------------------------

[](#constructor-options-reference)

OptionTypeDefaultDescription`url`string`API_DATA_FETCHER_BASE_URL`Base API URL`lang`string`"en"`Language code inserted into the URL; `""` disables it`default_params`array`["format" => "json"]`Parameters added to every request`additional_headers`array|string`[]`HTTP headers sent with every request`user_agent`string`ApiDataFetcher/x.y UrlFetcher/x.y`User-Agent header value`cache_storage`object`new CacheFileStorage()`Cache storage instance`socket_timeout`float`5.0`Connection timeout in seconds`proxy`string`""`Proxy URL, e.g. `"tcp://proxy:8118"``verify_peer`bool`true`Verify the SSL certificate`verify_peer_name`bool`true`Verify the SSL certificate hostname`automatically_add_leading_slash`bool`true`Ensure base URL ends with `/``automatically_add_trailing_slash`bool`true`Ensure action URL ends with `/``communicate_via_command`string|null`null`Path to a command used instead of a network socket`get_content_callback`callable—Custom callback to extract the response body from `UrlFetcher``logger`object|nullATK14 logger or `null`PSR-compatible loggerTracy panel integration
-----------------------

[](#tracy-panel-integration)

The package ships with `ApiDataFetcherPanel` for the [Tracy](https://tracy.nette.org) 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
-------

[](#license)

ApiDataFetcher is free software distributed [under the terms of the MIT license](http://www.opensource.org/licenses/mit-license).

###  Health Score

57

—

FairBetter than 98% of packages

Maintenance98

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 98.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~79 days

Recently: every ~19 days

Total

46

Last Release

7d ago

PHP version history (2 changes)v1.0PHP >=5.3.0

v1.10.7PHP >=5.6.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/974278?v=4)[Jaromir Tomek](/maintainers/yarri)[@yarri](https://github.com/yarri)

---

Top Contributors

[![yarri](https://avatars.githubusercontent.com/u/974278?v=4)](https://github.com/yarri "yarri (204 commits)")[![mysutka](https://avatars.githubusercontent.com/u/974669?v=4)](https://github.com/mysutka "mysutka (3 commits)")

---

Tags

apiclientrestfulatk14

### Embed Badge

![Health badge](/badges/atk14-api-data-fetcher/health.svg)

```
[![Health](https://phpackages.com/badges/atk14-api-data-fetcher/health.svg)](https://phpackages.com/packages/atk14-api-data-fetcher)
```

###  Alternatives

[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

46688.8k5](/packages/deepseek-php-deepseek-php-client)[skeeks/yii2-google-api

Component for work with google api based on google/apiclient

1143.8k1](/packages/skeeks-yii2-google-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)