esi/api

A simple wrapper/builder using Guzzle for base API clients.

v1.1.0 2024-05-22 02:33 UTC

Requires

• php: ^8.2 <8.5
• guzzlehttp/guzzle: ^7.0
• kevinrob/guzzle-cache-middleware: ^5.1
• symfony/cache: ^7.0

Requires (Dev)

• esi/phpunit-coverage-check: ^2.0
• friendsofphp/php-cs-fixer: ^3.57
• phpstan/phpstan: ^1.11
• phpstan/phpstan-phpunit: ^1.4
• phpstan/phpstan-strict-rules: ^1.6
• phpunit/phpunit: ^11.1

MIT

• Eric Sizemore

• api
• Guzzle
• API-Client
• guzzlehttp
• api-wrapper

README

esi/api is a simple wrapper/builder using Guzzle for base API clients.

Note

Documentation will be a bit lackluster, and the unit tests need a lot of work. With that being said, I created this library more for use in my own projects that center around an API service; to decouple a lot of the logic that would be repeated in each API service library, to its own library. It has a long way to go, but it should be relatively stable.

Installation

You can install the package via composer:

$ composer require ericsizemore/api

Features

• Builds around guzzle/guzzle as the HTTP Client.
• Cache's requests via Kevinrob/guzzle-cache-middleware.
• Can retry requets on a connection or server error via the Guzzle Retry Middleware.
  • Client::enableRetryAttempts() to instruct the client to attempt retries.
  • Client::disableRetryAttempts() to disable attempt retries.
  • Client::setMaxRetryAttempts() to set the maximum number of retries.
• Can pass along headers in Client::build() to be 'persistent' headers, i.e. headers sent with every request.
• One function that handles sending a request: Client::send()

It currently does not support async requests and pooling. Just your regular, good 'ol, standard requests.

Usage

use Esi\Api\Client;

// api url, api key, cache path, does the api require key sent as a query arg, the name of the query arg
$client = new Client('https://myapiurl.com/api', 'myApiKey', '/var/tmp', true, 'api_key');

// Must first 'build' the client with (optional) $options array which can include any valid Guzzle option.
$client->build([
    'persistentHeaders' => [
        'Accept' => 'application/json',
    ],
    'allow_redirects' => true,
    // ... etc.
]);
$client->enableRetryAttempts();
$client->setMaxRetryAttempts(5);

$response = $client->send('GET', '/', ['query' => ['foo' => 'bar']]);

// Decode the json and return as array
$data = $client->toArray($response);

// or... as an object
$data = $client->toObject($response);

// or... for the raw json response, to do with as you will
$data = $client->raw(); // or $response->getBody()->getContents()

Requirements

• PHP 8.2.0 or above.

Credits

• Eric Sizemore
• All Contributors

Contributing

See CONTRIBUTING.

Bugs and feature requests are tracked on GitHub.

Contributor Covenant Code of Conduct

See CODE_OF_CONDUCT.md

Backward Compatibility Promise

See backward-compatibility.md for more information on Backwards Compatibility.

Changelog

See the CHANGELOG for more information on what has changed recently.

License

See the LICENSE for more information on the license that applies to this project.

Security

See SECURITY for more information on the security disclosure process.