PHP Classes

How to Quickly Create a Client to Make Calls to a New API using APIz: Base client class to send requests to a given API

Recommend this page to a friend!
  Info   View files Documentation   View files View files (18)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2023-01-18 (15 days ago) RSS 2.0 feedNot yet rated by the usersTotal: 37 This week: 2All time: 10,584 This week: 153Up
Version License PHP version Categories
apiz 1.0MIT/X Consortium ...5HTTP, PHP 5, Web services
Description Author

This package provides a base client class to send requests to a given API.

It provides a base class that developers should extend to create a sub-class that will be a client class for a given API.

The package provides functions the new API client class can override or call to implement functions that applications can call to make calls to the API.

Developers that want to create a new API client with this need to have functions in a sub-class of this package.

The sub-class needs to define the API base URL and other functions that wrap the calls to the API using functions that send HTTP requests to the API and return the response values.

Picture of Nahid Bin Azhar
  Performance   Level  
Name: Nahid Bin Azhar <contact>
Classes: 22 packages by
Country: Bangladesh Bangladesh
Age: 32
All time rank: 82313 in Bangladesh Bangladesh
Week rank: 57 Up3 in Bangladesh Bangladesh Up
Innovation award
Innovation award
Nominee: 5x

Winner: 2x

Details

APIZ

APIZ is a PHP API Client Development Kit, it helps you to manage HTTP API call in OOP way. You can easily handle and isolate all kinds of REST API calls and their responses by using this package.

Requirements

  • PHP >= 5.5.9

Installations

composer require nahid/apiz

Configurations

There are no extra configurations for this package.

Usage

Lets see an example to consume API from https://reqres.in.

Suppose you need to create several API services for your project. Your service directory is app/Services. Now we are going to develop a service for https://reqres.in and make a class file ReqResApiService.php which will extend \Apiz\AbstractApi class.

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }
}

getBaseURL() is an abstract method of the AbstractApi class. You need to override this method to set the proper base URL for your API.

Few APIs have a common prefix in their URL. Like, here reqres.in have a prefix api on every endpoint. So, we'll override the getPrefix() method to define the Prefix.

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }

    protected function getPrefix()
    {
        return 'api';
    }
}

Now let's make a method to get all users info.

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }

    protected function getPrefix()
    {
        return 'api';
    }

    public function getAllUsers()
    {
        $response = $this->get('users');

        if ($response->getStatusCode() === 200) {
            return $response()->toArray();
        }

        return [];
    }
}

So, we are basically making a GET request to the URL https://reqres.in/api/users.

See, how easy it is to manage an API now?

Let's see another example.

Post Request with Form Params

public function createUser(array $data)
{
    $response = $this->withFormParams($data)
            ->post('create');

    if ($response->getStatusCode() === 201) {
        return $response()->toArray();
    }

    return null;
}

Default Headers

Sometimes we need to bind some headers with all the requests. Suppose if you want to deal with the Github API, you have to send access_token in every request with the headers. So APIZ provide you a handy way to deal with this problem. Just override AbstractApi::getDefaultHeaders().

protected function getDefaultHeaders()
{
    return [
        'access_token' => $_ENV['GITHUB_ACCESS_TOKEN'],
    ];
}

Cool, right?

You can easily use all HTTP verbs like get, post etc. It's totally hassle free. See more examples in the Examples Folder.

Query over Response Data

Sometimes we receive huge payload as a response from the APIs. It's quite daunting to parse proper data from that big payload.

No worries! We're using a powerful Query parser, named QArray by default to parse and query over the Response data.

Let's see how we can use this parser to parse the response we got for getAllUsers method from our previous example.

public function getFirstUser()
{
    $users = $this->get('users');
    return $users->query()->from('data')->first();
}

We're getting list of users in the data key in the response. From that we're collecting the first data. See, how easy it is!

You can find detail usage of the QArray here.

Additionally, there is a secret sauce for you.

If you don't want to query like: $users->query(), you can just do it like this: $users(). That means the response object is invokable and behave exactly like calling the query() method.

You're welcome. :D

Overriding HTTP Client

By default we are using Guzzle as our HTTP Client. But you are not bound to use this. You can easily use your own PSR7 supported HTTP Client with Apiz. Just pass an instance of your HTTP Client to our setClient() method. See an example here.

Here is our GuzzleClient to get an idea how your Client should look like:

<?php

namespace Apiz\Http\Clients;

use Apiz\Http\AbstractClient;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;
use GuzzleHttp\Psr7\Uri;
use GuzzleHttp\Exception\GuzzleException;
use Psr\Http\Message\ResponseInterface;

// Your client must extend the `AbstractClient`
class GuzzleClient extends AbstractClient
{
    public function getRequestClass()
    {
        // Return the Request class name of your PSR7 supported Client
        // This Request class must implement the Psr\Http\Message\RequestInterface
        return Request::class;
    }

    public function getResponseClass()
    {
        // Return the Response class name of your PSR7 supported Client
        // This Response class must implement the Psr\Http\Message\ResponseInterface        
        return Response::class;
    }

    public function getUriClass()
    {
        // Return the Uri class name of your PSR7 supported Client
        // This Uri class must implement the Psr\Http\Message\UriInterface        
        return Uri::class;
    }

    /
     * @param mixed ...$args
     * @return ResponseInterface
     * @throws GuzzleException
     */
    public function send(...$args)
    {
        // In this method, implement how your Client execute the Request sending
        $client = new Client();

        return $client->send(... $args);
    }
}

List of methods for common HTTP verbs

  • `get(string $uri)`
  • `post(string $uri)`
  • `put(string $uri)`
  • `delete(string $uri)`
  • `head(string $uri)`
  • `options(string $uri)`

List of Available methods

  • `getPrefix():string`: override this method to define the common prefix, if you need it
  • `setClient($client)` : pass a PSR7 supported Client instance, only if you need to override the default Guzzle HTTP Client
  • `withFormParams(array)`: pass Form parameters data for requests like POST, PATCH, UPDATE
  • `withHeaders(array)`: pass Header data
  • `withQueryParams(array)`: pass Query Parameter data
  • `withFormData(array)`: pass Multipart form data
  • `getDefaultHeaders():array`: override to define default Headers, if you have any
  • `getDefaultQueries():array`: override to define default queries, if you have any
  • `skipDefaultHeaders(bool)`
  • `skipDefaultQueries(bool)`
  • `allowRedirects(array)`
  • `basicAuth(string $username, string $password [, array $options])`
  • `body(string)`: Set request body
  • `json(array)`: Set JSON data to be passed as Request Body
  • `file(string $name, string $file_path, string $filename [, array $headers])`
  • `params(array $params)`

Contribution

Feel free send feedback and issues. Contributions to improve this package is most welcome too.

  Files folder image Files  
File Role Description
Files folder imagesrc (3 files, 5 directories)
Files folder imageTests (1 directory)
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file readme.md Doc. Read me

  Files folder image Files  /  src  
File Role Description
Files folder imageConstants (1 file)
Files folder imageExceptions (3 files)
Files folder imageHttp (2 files, 1 directory)
Files folder imageTraits (1 file)
Files folder imageUtilities (1 file)
  Plain text file AbstractApi.php Class Class source
  Plain text file HttpExceptionReceiver.php Class Class source
  Plain text file QueryBuilder.php Class Class source

  Files folder image Files  /  src  /  Constants  
File Role Description
  Plain text file MimeType.php Class Class source

  Files folder image Files  /  src  /  Exceptions  
File Role Description
  Plain text file ClientNotDefinedException.php Class Class source
  Plain text file InvalidResponseClassException.php Class Class source
  Plain text file NoResponseException.php Class Class source

  Files folder image Files  /  src  /  Http  
File Role Description
Files folder imageClients (2 files)
  Plain text file Request.php Class Class source
  Plain text file Response.php Class Class source

  Files folder image Files  /  src  /  Http  /  Clients  
File Role Description
  Plain text file AbstractClient.php Class Class source
  Plain text file GuzzleClient.php Class Class source

  Files folder image Files  /  src  /  Traits  
File Role Description
  Plain text file Hookable.php Class Class source

  Files folder image Files  /  src  /  Utilities  
File Role Description
  Plain text file Parser.php Class Class source

  Files folder image Files  /  Tests  
File Role Description
Files folder imageFeature (1 file, 1 directory)

  Files folder image Files  /  Tests  /  Feature  
File Role Description
Files folder imageMocks (1 file)
  Plain text file BasicHTTPRequestsTest.php Class Class source

  Files folder image Files  /  Tests  /  Feature  /  Mocks  
File Role Description
  Plain text file BasicHTTPAPI.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:37
This week:2
All time:10,584
This week:153Up