othercode/rest

Rest client to make GET, POST, PUT, DELETE, PATCH, etc calls.

v1.5.0 2023-10-10 09:32 UTC

Requires

• php: >=7.4.33
• ext-curl: *
• ext-json: *
• ext-simplexml: *
• ext-xmlrpc: *

Requires (Dev)

• pestphp/pest: ^1.0
• phpunit/phpunit: *

MIT

• Unay Santisteban

• curl
• http
• rest
• requests

README

Rest client to make GET, POST, PUT, DELETE, PATCH, etc.

Installation

To install the package we only have to add the dependency to composer.json file:

{
  "require": {
    "othercode/rest": "*"
  }
}

And run the following command:

composer install

Usage

To use the Rest we only have to instantiate it and configure the params we want. We can establish the configuration accessing to the ->configuration->configure_property, for example to configure the url of the call we only have to set the ->configuration->url parameter like we can see as follows:

$api = new \OtherCode\Rest\Rest();
$api->configuration->url = "https://jsonplaceholder.typicode.com/";

or

$api = new \OtherCode\Rest\Rest(new \OtherCode\Rest\Core\Configuration(array(
    'url' => 'https://jsonplaceholder.typicode.com/',
)));

After this we have to set the type of call and the parameters that we wil use, in this case we are going to perform a GET request to the "posts/1" endpoint:

$response = $api->get("posts/1");

The rest client will throw a ConnectionException if there are any problem related to the connection.

NOTE: These errors are related to the session cURL, here is the complete list

Methods

The available methods to work with are:

get()

Perform a GET request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made
$data	Array	Optional. Associative array of data parameters

Return: Response object

head()

Perform a HEAD request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made

Return: Response object (no body)

post()

Perform a POST request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made
$data	Array	Optional. Associative array of data parameters

Return: Response object

delete()

Perform a DELETE request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made
$data	Array	Optional. Associative array of data parameters

Return: Response object

put()

Perform a PUT request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made
$data	Array	Optional. Associative array of data parameters

Return: Response object

patch()

Perform a PATCH request.

Parameters	Type	Description
$url	String	Required. The URL to which the request is made
$data	Array	Optional. Associative array of data parameters

Return: Response object

getMetadata()

Return the metadata of the request.

Return: Array

getError()

Return the last known error.

Return: Error object

getPayloads()

Return an array with the Response and Request objects.

Return: Array

setDecoder()

Set a new Decoder.

Parameters	Type	Description
$name	String	Required. The unique name of the decoder.
$decoder	String	Optional. The class name with namespace of the new decoder.

Return: Rest object

setEncoder()

Set a new Encoder.

Parameters	Type	Description
$name	String	Required. The unique name of the encoder.
$encoder	String	Optional. The class name with namespace of the new encoder.

Return: Rest object

setModule()

Set a new Module.

Parameters	Type	Description
$name	String	Required. The unique name of the module.
$module	String	Required. The class name with namespace of the new module.
$hook	String	Optional. The hook name (after/before) that will trigger the module, 'after' by default.

Return: Rest object

unsetModule()

Unregister a module.

Parameters	Type	Description
$moduleName	String	Required. The unique name of the decoder.
$hook	String	Optional. The hook name (after/before) from where delete the module.

Return: Rest object

addHeader()

Add a new header.

Parameters	Type	Description
$header	String	Required. The unique name of the header.
$value	String	Requires. The value of the header.

Return: Rest object

addHeaders()

Add an array of headers.

Parameters	Type	Description
$headers	String	Required. An array of headers.

Return: Rest object

NOTE: We can use the addHeader() and addHeaders() methods with the Rest instance or with the configuration object

$api->addHeader('some_header','some_value');
$api->addHeaders(array('some_header' => 'some_value','other_header' => 'other_value'));

is the same as

$api->configuration->addHeader('some_header','some_value');
$api->configuration->addHeaders(array('some_header' => 'some_value','other_header' => 'other_value'));

removeHeader()

Remove a header offset.

Parameters	Type	Description
$header	String	Required. The unique name of the header.

Return: Rest object

removeHeaders()

Remove an array of headers.

Parameters	Type	Description
$headers	String	Required. An array of headers to remove.

Return: Rest object

Modules

This package allow you to create modules to perform task before and after the request. To create a new module we only have to use this template:

class CustomModule extends BaseModule
{
    public function run()
    {
        // do something
    }
}

IMPORTANT: Any module MUST extends BaseModule

The only method that is mandatory is ->run(), this method execute your custom code of the module.

Once we have our module we can register it with the ->setModule() method. This method needs three parameters, the first one is the name of the module, the second one is the complete namespace of the module, and the third one is the hook name for our module, it can be "before" and "after" depends on when we want to launch our module.

$api->setModule('module_name','Module\Complete\Namespace','after');

For "before" modules you can use all the properties of the Request object.

• method
• url
• headers
• body

For "after" modules you can use all the properties of the Response object.

• code
• content_type
• charset
• body
• headers
• error
• metadata

All modules are executed in the order that we register them into the Rest client, this also affect to Decoders and Encoders.

Decoders

A decoder is a kind of module that allows you to automatically decode de response in xml or json, to use them we only have to set the decoder we want with the ->setDecoder() method:

$api->setDecoder("json");

The default allowed values for this method are: json, xml and xmlrpc. All the decoders are always executed in the "after" hook.

Custom Decoders

To create a new decoder we only have to use this template:

class CustomDecoder extends BaseDecoder
{
	protected $contentType = 'application/json';

	protected function decode()
	{
		// decode $this->body
	}
}

Like in modules, we have the Response object available to work. The $contentType property is the content-type that will trigger the decoder, in the example above all responses with content-type "application/json" will trigger this decoder.

Quick Calls

We can do quick calls using the \OtherCode\Rest\Payloads\Request::call() method. This static method returns a Rest instance, so we can use all the methods from it.

$response = \OtherCode\Rest\Payloads\Request::call('https://jsonplaceholder.typicode.com')
    ->setDecoder('json')
    ->get('/posts/1');

Complete Example

require_once '../autoload.php';

try {

    $api = new \OtherCode\Rest\Rest(new \OtherCode\Rest\Core\Configuration(array(
        'url' => 'https://jsonplaceholder.typicode.com/',
        'httpheader' => array(
            'some_header' => 'some_value',
        )
    )));
    $api->setDecoder("json");
    
    $response = $api->get("posts/1");
    var_dump($response);
    
} catch (\Exception $e) {
    print "> " . $e->getMessage() . "\n"
}