PHP code example of programmatordev / php-api-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

programmatordev / php-api-sdk example snippets

use ProgrammatorDev\Api\Api;

class YourApi extends Api
{
    public function __construct() 
    {
        parent::__construct();
        
        // minimum ple.com/v1/posts?page=1
        return $this->request(
            method: 'GET',
            path: '/posts',
            query: [
               'page' => $page
            ]
        );
    }
}

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

$this->getBaseUrl(): string

use Psr\Http\Message\StreamInterface;

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

use ProgrammatorDev\Api\Api;

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

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

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
            ])
        );
    }
}

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

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

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

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'
            ]
        );
    }
}

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

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

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

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'
            ]
        );
    }
}

use Http\Message\Authentication;

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

use Http\Message\Authentication;

$this->getAuthentication(): ?Authentication;

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'
        );
    }
}

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

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
                // ...
            }
        });
    }
    
    // ...
}

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

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

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()
                };
            }
        });
    }
    
    // ...
}

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

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

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'
        );
    }
}

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

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
        ); 
    }
}

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) { 
            // ...
        }); 
    }
}

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;

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
            )
        );
    }
}

use Http\Client\Common\Plugin;

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

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
        );
    }
}

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;

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'
        );
    }
}

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;

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
            )
        );
    }
}

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 

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

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

bash
composer