README

A library for creating SDKs in PHP with support for:

PSR-18 HTTP clients;
PSR-17 HTTP factories;
PSR-6 caches;
PSR-3 logs;
Authentication;
Event listeners;
...and more.

All methods are public for full hackability 🔥.

Requirements

PHP 8.1 or higher.

Installation

Install the library via Composer:

composer require programmatordev/php-api-sdk

Basic Usage

Just extend your API library with the Api class and have fun coding:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct() 
    {
        parent::__construct();
        
        // minimum required config
        $this->setBaseUrl('https://api.example.com/v1');
    }
    
    public function getPosts(int $page = 1): string
    {
        // GET https://api.example.com/v1/posts?page=1
        return $this->request(
            method: 'GET',
            path: '/posts',
            query: [
               'page' => $page
            ]
        );
    }
}

Documentation

Base URL
Requests
Query defaults
Header defaults
Authentication
Event listeners
HTTP client (PSR-18) and HTTP factories (PSR-17)
Cache (PSR-6)
Logger (PSR-3)
Configure options

Base URL

Getter and setter for the base URL. Base URL is the common part of the API URL and will be used in all requests.

$this->setBaseUrl(string $baseUrl): self

$this->getBaseUrl(): string

`request`

This method is used to send a request to an API.

use Psr\Http\Message\StreamInterface;

$this->request(
    string $method, 
    string $path, 
    array $query [], 
    array $headers = [], 
    StreamInterface|string $body = null
): mixed

Note

A ConfigException will be thrown if a base URL is not set (this is, if it is empty). Check the setBaseUrl method for more information.

Note

A ClientException will be thrown if there is an error while processing the request.

For example, if you wanted to get a list of users with pagination:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct() 
    {
        parent::__construct();
        
        // minimum required config
        $this->setBaseUrl('https://api.example.com/v1');
    }
    
    public function getUsers(int $page = 1, int $perPage = 20): string
    {
        // GET https://api.example.com/v1/users?page=1&limit=20
        return $this->request(
            method: 'GET',
            path: '/users',
            query: [
                'page' => $page,
                'limit' => $perPage
            ]
        );
    }
}

By default, this method will return a string as it will be the response of the request as is. If you want to change how the response is handled in all requests (for example, decode a JSON string into an array), check the addResponseContentsListener method in the Event Listeners section.

`buildPath`

The purpose of this method is to have an easy way to build a properly formatted path depending on the inputs or parameters you might have.

$this->buildPath(string $path, array $parameters): string;

For example, if you want to build a path that has a dynamic id:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct() 
    {
        parent::__construct();
        
        $this->setBaseUrl('https://api.example.com/v1');
    }
    
    public function getPostComments(int $postId): string
    {
        // GET https://api.example.com/v1/posts/1/comments
        return $this->request(
            method: 'GET',
            path: $this->buildPath('/posts/{postId}/comments', [
                'postId' => $postId
            ])
        );
    }
}

Query Defaults

These methods are used for handling default query parameters. Default query parameters are applied to every API request.

$this->addQueryDefault(string $name, mixed $value): self

$this->getQueryDefault(string $name): mixed

$this->removeQueryDefault(string $name): self

For example, if you want to add a language query parameter in all requests:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct(string $language = 'en') 
    {
        // ...
        
        $this->addQueryDefault('lang', $language);
    }
    
    public function getPosts(): string
    {
        // GET https://api.example.com/v1/posts?lang=en
        return $this->request(
            method: 'GET',
            path: '/posts'
        );
    }
    
    public function getCategories(): string
    {
        // a query parameter with the same name, passed in the request method, will overwrite a query default
        // GET https://api.example.com/v1/categories?lang=pt
        return $this->request(
            method: 'GET',
            path: '/categories',
            query: [
                'lang' => 'pt'
            ]
        );
    }
}

Note

A query parameter with the same name, passed in the request method, will overwrite a query default. Check the getCategories method in the example above.

Header Defaults

These methods are used for handling default headers. Default headers are applied to every API request.

$this->addHeaderDefault(string $name, mixed $value): self

$this->getHeaderDefault(string $name): mixed

$this->removeHeaderDefault(string $name): self

For example, if you want to add a language header value in all requests:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct(string $language = 'en') 
    {
        // ...
        
        $this->addHeaderDefault('X-LANGUAGE', $language);
    }
    
    public function getPosts(): string
    {
        // GET https://api.example.com/v1/posts with an 'X-LANGUAGE' => 'en' header value
        return $this->request(
            method: 'GET',
            path: '/posts'
        );
    }
    
    public function getCategories(): string
    {
        // a header with the same name, passed in the request method, will overwrite a header default
        // GET https://api.example.com/v1/categories with an 'X-LANGUAGE' => 'pt' header value
        return $this->request(
            method: 'GET',
            path: '/categories',
            headers: [
                'X-LANGUAGE' => 'pt'
            ]
        );
    }
}

Note

A header with the same name, passed in the request method, will overwrite a header default. Check the getCategories method in the example above.

Authentication

Getter and setter for API authentication. Uses the authentication component from PHP HTTP.

use Http\Message\Authentication;

$this->setAuthentication(?Authentication $authentication): self;

use Http\Message\Authentication;

$this->getAuthentication(): ?Authentication;

Available authentication methods:

BasicAuth Username and password
Bearer Token
Wsse Username and password
QueryParam Array of query parameter values
Header Header name and value
Chain Array of authentication instances
RequestConditional A request matcher and authentication instances

You can also implement your own authentication method.

For example, if you have an API that is authenticated with a query parameter:

use ProgrammatorDev\Api\Api;
use Http\Message\Authentication\QueryParam;

class YourApi extends Api
{
    public function __construct(string $applicationKey) 
    {
        // ...
        
        $this->setAuthentication(
            new QueryParam([
                'api_token' => $applicationKey
            ])
        );
    }
    
    public function getPosts(): string
    {
        // GET https://api.example.com/v1/posts?api_token=cd982h3diwh98dd23d32j
        return $this->request(
            method: 'GET',
            path: '/posts'
        );
    }
}

Event Listeners

addPreRequestListener
addPostRequestListener
addResponseContentsListener
Event Priority
Event Propagation

`addPreRequestListener`

The addPreRequestListener method is used to add a function that is called before a request has been made. This event listener will be applied to every API request.

$this->addPreRequestListener(callable $listener, int $priority = 0): self;

For example:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Event\PreRequestEvent;

class YourApi extends Api
{
    public function __construct() 
    {
        // a PreRequestEvent is passed as an argument
        $this->addPreRequestListener(function(PreRequestEvent $event) {
            $request = $event->getRequest();
            
            if ($request->getMethod() === 'POST') {
                // do something for all POST requests
                // ...
            }
        });
    }
    
    // ...
}

Available event methods:

$this->addPreRequestListener(function(PreRequestEvent $event) {
    // get request data
    $request = $event->getRequest();
    // ...
    // set request data
    $event->setRequest($request);
});

`addPostRequestListener`

The addPostRequestListener method is used to add a function that is called after a request has been made. This function can be used to inspect the request and response data that was sent to, and received from, the API. This event listener will be applied to every API request.

$this->addPostRequestListener(callable $listener, int $priority = 0): self;

For example, you can use this event listener to handle API errors:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Event\PostRequestEvent;

class YourApi extends Api
{
    public function __construct() 
    {
        // a PostRequestEvent is passed as an argument
        $this->addPostRequestListener(function(PostRequestEvent $event) {
            $response = $event->getResponse();
            $statusCode = $response->getStatusCode();
            
            // if there was a response with an error status code
            if ($statusCode >= 400) {
                // throw an exception
                match ($statusCode) {
                    400 => throw new BadRequestException(),
                    404 => throw new NotFoundException(),
                    default => throw new UnexpectedErrorException()
                };
            }
        });
    }
    
    // ...
}

Available event methods:

$this->addPostRequestListener(function(PostRequestEvent $event) {
    // get request data
    $request = $event->getRequest();
    // get response data
    $response = $event->getResponse();
    // ...
    // set response data
    $event->setResponse($response);
});

`addResponseContentsListener`

The addResponseContentsListener method is used to manipulate the response that was received from the API. This event listener will be applied to every API request.

$this->addResponseContentsListener(callable $listener, int $priority = 0): self;

For example, if the API responses are JSON strings, you can use this event listener to decode them into arrays:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Event\ResponseContentsEvent;

class YourApi extends Api
{
    public function __construct() 
    {
        // a ResponseContentsEvent is passed as an argument
        $this->addResponseContentsListener(function(ResponseContentsEvent $event) {
            // get response contents and decode json string into an array
            $contents = $event->getContents();
            $contents = json_decode($contents, true);
            
            // set handled contents
            $event->setContents($contents);
        });
    }
    
    public function getPosts(): array
    {
        // will return an array
        return $this->request(
            method: 'GET',
            path: '/posts'
        );
    }
}

Available event methods:

$this->addResponseContentsListener(function(ResponseContentsEvent $event) {
    // get response body contents data
    $contents = $event->getContents();
    // ...
    // set contents
    $event->setContents($contents);
});

Event Priority

It is possible to add multiple listeners for the same event and set the order in which they will be executed. By default, they will be executed in the same order as they are added, but you can set a priority to control that order. Event listeners are then executed from the highest priority to the lowest:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Event\ResponseContentsEvent;

class YourApi extends Api
{
    public function __construct() 
    {
        // two event listeners are added,
        // but the second is executed first (higher priority) even though it was added after
        
        // executed last (lower priority)
        $this->addResponseContentsListener(
            listener: function(ResponseContentsEvent $event) { ... }, 
            priority: 0
        );
        
        // executed first (higher priority)
        $this->addResponseContentsListener(
            listener: function(ResponseContentsEvent $event) { ... }, 
            priority: 10
        ); 
    }
}

Event Propagation

In some cases, you may want to stop the event flow and prevent listeners from being called. For that, you can use the stopPropagation() method:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Event\ResponseContentsEvent;

class YourApi extends Api
{
    public function __construct() 
    {
        $this->addResponseContentsListener(function(ResponseContentsEvent $event) {
            // stop propagation so future listeners of this event will not be called
            $event->stopPropagation();
        });
        
        // this listener will not be called
        $this->addResponseContentsListener(function(ResponseContentsEvent $event) { 
            // ...
        }); 
    }
}

HTTP Client (PSR-18) and HTTP Factories (PSR-17)

HTTP client and HTTP factory adapters
Plugin system

HTTP Client and HTTP Factory Adapters

By default, this library makes use of the HTTPlug's Discovery library. This means that it will automatically find and install a well-known PSR-18 client and PSR-17 factory implementation for you (if they were not found on your project):

use ProgrammatorDev\Api\Builder\ClientBuilder;

new ClientBuilder(
    // a PSR-18 client
    ?ClientInterface $client = null,
    // a PSR-17 request factory
    ?RequestFactoryInterface $requestFactory = null,
    // a PSR-17 stream factory
    ?StreamFactoryInterface $streamFactory = null
);

use ProgrammatorDev\Api\Builder\ClientBuilder;

$this->setClientBuilder(ClientBuilder $clientBuilder): self;

use ProgrammatorDev\Api\Builder\ClientBuilder;

$this->getClientBuilder(): ClientBuilder;

If you don't want to rely on the discovery of implementations, you can set the ones you want:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Builder\ClientBuilder;
use Symfony\Component\HttpClient\Psr18Client;
use Nyholm\Psr7\Factory\Psr17Factory;

class YourApi extends Api
{
    public function __construct() 
    {
        // ...
        
        $client = new Psr18Client();
        $requestFactory = $streamFactory = new Psr17Factory();
        
        $this->setClientBuilder(
            new ClientBuilder(
                client: $client, 
                requestFactory: $requestFactory, 
                streamFactory: $streamFactory
            )
        );
    }
}

Plugin System

This library enables attaching plugins to the HTTP client. A plugin modifies the behavior of the client by intercepting the request and response flow.

Since plugin order matters, a plugin is added with a priority level, and are executed in descending order from highest to lowest.

Check all the available plugins or create your own.

use Http\Client\Common\Plugin;

$this->getClientBuilder()->addPlugin(Plugin $plugin, int $priority): self;

Note

A PluginException will be thrown if there is a plugin with the same priority level.

It is important to know that this library already uses various plugins with different priorities. The following list has all the implemented plugins with the respective priority in descending order (remember that order matters):

For example, if you wanted the client to automatically attempt to re-send a request that failed (due to unreliable connections and servers, for example) you can add the RetryPlugin:

use ProgrammatorDev\Api\Api;
use Http\Client\Common\Plugin\RetryPlugin;

class YourApi extends Api
{
    public function __construct() 
    {
        // ...
        
        // if a request fails, it will retry at least 3 times
        // priority is 20 to execute before the cache plugin
        // (check the above plugin order list for more information)
        $this->getClientBuilder()->addPlugin(
            plugin: new RetryPlugin(['retries' => 3]),
            priority: 20
        );
    }
}

Cache (PSR-6)

This library allows configuring the cache layer of the client for making API requests. It uses a standard PSR-6 implementation and provides methods to fine-tune how HTTP caching behaves:

PSR-6 compatible implementations

use ProgrammatorDev\Api\Builder\CacheBuilder;
use Psr\Cache\CacheItemPoolInterface;

new CacheBuilder(
    // a PSR-6 cache adapter
    CacheItemPoolInterface $pool,
    // default lifetime (in seconds) of cache items
    ?int $ttl = 60,
    // An array of HTTP methods for which caching should be applied
    $methods = ['GET', 'HEAD'],
    // An array of cache directives to be compared with the headers of the HTTP response,
    // in order to determine cacheability
    $responseCacheDirectives = ['max-age'] 
);

use ProgrammatorDev\Api\Builder\CacheBuilder;

$this->setCacheBuilder(CacheBuilder $cacheBuilder): self;

use ProgrammatorDev\Api\Builder\CacheBuilder;

$this->getCacheBuilder(): CacheBuilder;

For example, if you wanted to set a file-based cache adapter:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Builder\CacheBuilder;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

class YourApi extends Api
{
    public function __construct() 
    {
        // ...
        
        $pool = new FilesystemAdapter();
        
        // file-based cache adapter with a 1-hour default cache lifetime
        $this->setCacheBuilder(
            new CacheBuilder(
                pool: $pool, 
                ttl: 3600
            )
        );
    }
    
    public function getPosts(): string
    {
        // you can change the lifetime (and all other parameters)
        // for this specific endpoint
        $this->getCacheBuilder()->setTtl(600);
       
        return $this->request(
            method: 'GET',
            path: '/posts'
        );
    }
}

Logger (PSR-3)

This library allows configuring a logger to save data for making API requests. It uses a standard PSR-3 implementation and provides methods to fine-tune how logging behaves:

PSR-3 compatible implementations

use ProgrammatorDev\Api\Builder\LoggerBuilder;
use Psr\Log\LoggerInterface;
use Http\Message\Formatter;
use Http\Message\Formatter\SimpleFormatter;

new LoggerBuilder(
    // a PSR-3 logger adapter
    LoggerInterface $logger,
     // determines how the log entries will be formatted when they are written by the logger
     // if no formatter is provided, it will default to a SimpleFormatter instance
    ?Formatter $formatter = null
);

use ProgrammatorDev\Api\Builder\LoggerBuilder;

$this->setLoggerBuilder(LoggerBuilder $loggerBuilder): self;

use ProgrammatorDev\Api\Builder\LoggerBuilder;

$this->getLoggerBuilder(): LoggerBuilder;

As an example, if you wanted to save logs into a file:

use ProgrammatorDev\Api\Api;
use ProgrammatorDev\Api\Builder\LoggerBuilder;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

class YourApi extends Api
{
    public function __construct() 
    {
        // ...
        
        $logger = new Logger('api');
        $logger->pushHandler(new StreamHandler('/logs/api.log'));
        
        $this->setLoggerBuilder(
            new LoggerBuilder(
                logger: $logger
            )
        );
    }
}

Configure Options

It is very common for APIs to offer different options (like language, timezone, etc.). To simplify the process of configuring options, the OptionsResolver is available. It allows you to create a set of default options and their constraints such as required options, default values, allowed types, etc. It then resolves the given options array against these default options to ensure it meets all the constraints.

For example, if an API has a language and timezone options:

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    private array $options = [];

    public function __construct(array $options = []) 
    {
        parent::__construct();
        
        $this->options = $this->configureOptions($options);
        $this->configureApi();
    }
    
    private function configureOptions(array $options): array
    {
        // set defaults values, if none were provided
        $this->optionsResolver->setDefault('timezone', 'UTC');
        $this->optionsResolver->setDefault('language', 'en');

        // set allowed types
        $this->optionsResolver->setAllowedTypes('timezone', 'string');
        $this->optionsResolver->setAllowedTypes('language', 'string');

        // set allowed values
        $this->optionsResolver->setAllowedValues('timezone', \DateTimeZone::listIdentifiers());
        $this->optionsResolver->setAllowedValues('language', ['en', 'pt']);
        
        // return resolved options
        return $this->optionsResolver->resolve($options);
    }
    
    private function configureApi(): void
    {
        // set required base url
        $this->setBaseUrl('https://api.example.com/v1');
        
        // set options as query defaults (will be included in all requests)
        $this->addQueryDefault('language', $this->options['language']);
        $this->addQueryDefault('timezone', $this->options['timezone']);
    }
    
    public function getPosts(int $page = 1): string
    {
        // GET https://api.example.com/v1/posts?language=en&timezone=UTC&page=1
        return $this->request(
            method: 'GET',
            path: '/posts',
            query: [
                'page' => $page
            ]
        );
    }
}

When using the API, it should look like this:

$api = new YourApi([
    'language' => 'pt'
]);

// GET https://api.example.com/v1/posts?language=pt&timezone=UTC&page=1
$posts = $api->getPosts();

For all available methods, check the official page documentation.

Libraries using PHP API SDK

Contributing

Any form of contribution to improve this library (including requests) will be welcome and appreciated. Make sure to open a pull request or issue.

License

This project is licensed under the MIT license. Please see the LICENSE file distributed with this source code for further information regarding copyright and licensing.

programmatordev / php-api-sdk

Maintainers

Details

README

Requirements

Installation

Basic Usage

Documentation

Base URL

Requests

`request`

`buildPath`

Query Defaults

Header Defaults

Authentication

Event Listeners

`addPreRequestListener`

`addPostRequestListener`

`addResponseContentsListener`

Event Priority

Event Propagation

HTTP Client (PSR-18) and HTTP Factories (PSR-17)

HTTP Client and HTTP Factory Adapters

Plugin System

Cache (PSR-6)

Logger (PSR-3)

Configure Options

Libraries using PHP API SDK

Contributing

License