README

https://github.com/tcdent/php-restclient
(c) 2013-2022 Travis Dent tcdent@gmail.com

Installation

Requires PHP 7.2 or above. Use 0.1.7 for legacy versions of PHP.

$ composer require tcdent/php-restclient

Basic Usage

$api = new RestClient([
    'base_url' => "https://api.twitter.com/1.1", 
    'format' => "json", 
     // https://dev.twitter.com/docs/auth/application-only-auth
    'headers' => ['Authorization' => 'Bearer '.OAUTH_BEARER], 
]);
$result = $api->get("search/tweets", ['q' => "#php"]);
// GET http://api.twitter.com/1.1/search/tweets.json?q=%23php
if($result->info->http_code == 200)
    var_dump($result->decode_response());

Configurable Options

headers - An associative array of HTTP headers and values to be included in every request.
parameters - An associative array of URL or body parameters to be included in every request.
curl_options - cURL options to apply to every request; anything defined here: https://secure.php.net/manual/en/function.curl-setopt.php. These will override any automatically generated values.
build_indexed_queries (bool) - http_build_query automatically adds an array index to repeated parameters which is not desirable on most systems. Use this option to enable the default behavior. Defaults to FALSE. user_agent - User agent string to use in requests.
base_url - URL to use for the base of each request.
format - Format string is appended to resource on request (extension), and used to determine which decoder to use on response; a request URL like "api.twitter.com/1.1/statuses/user_timeline.json" would be expected to return well-formed JSON.
format_regex - Pattern to extract format from response Content-Type header, used to determine which decoder to use on response.
decoders - Associative array of format decoders. See "Direct Iteration and Response Decoding".
username - Username to use for HTTP basic authentication. Requires password.
password - Password to use for HTTP basic authentication. Requires username.

Options can be set upon instantiation, or individually afterword:

$api = new RestClient([
    'format' => "json", 
    'user_agent' => "my-application/0.1"
]);

-or-

$api = new RestClient;
$api->set_option('format', "json");
$api->set_option('user_agent', "my-application/0.1");

Standard Verbs

Four HTTP verbs are implemented as convenience methods: get(), post(), put() and delete(). Each accepts three arguments:

url (string) - URL of the resource you are requesting. Will be prepended with the value of the base_url option, if it has been configured. Will be appended with the value of the format option, if it has been configured.

parameters (string), (array) - String or associative array to be appended to the URL in GET requests and passed in the request body on all others. If an array is passed it will be encoded into a query string. A nested, indexed array is passed for parameters with multiple values and will be iterated to populate duplicate keys See: "Duplicate Headers and Parameters"

headers (array) - An associative array of headers to include with the request. A nested, indexed array is passed for parameters with multiple values and will be iterated to populate duplicate keys See: "Duplicate Headers and Parameters"

Other Verbs

You can make a request using any verb by calling execute() directly, which accepts four arguments: url, method, parameters and headers. All arguments expect the same values as in the convenience methods, with the exception of the additional method argument:

method (string) - HTTP verb to perform the request with.

Response Details

After making a request with one of the HTTP verb methods, or execute, the returned instance will have the following data populated:

response (string)- The raw response body content. See "Direct Iteration and Response Decoding" for ways to parse and access this data.

headers (object) - An object with all of the response headers populated. Indexes are transformed to snake_case for access. Duplicate headers are available as an indexed array under the shared key.

$response->headers->content_type;
$response->headers->x_powered_by;

info (object) - An object with information about the transaction. Populated by casting curl_info to an object. See PHP documentation for more info: http://php.net/manual/en/function.curl-getinfo.php Available attributes are:

url, content_type, http_code, header_size, request_size, filetime, 
ssl_verify_result, redirect_count, total_time, namelookup_time, connect_time, 
pretransfer_time, size_upload, size_download, speed_download, speed_upload, 
download_content_length, upload_content_length, starttransfer_time, redirect_time, 
certinfo, primary_ip, primary_port, local_ip, local_port, redirect_url

error (string) - cURL error message, if applicable.

response_status_lines (array) - Indexed array of raw HTTP response status lines. See: "Multiple HTTP Status Lines".

Direct Iteration and Response Decoding

If the the response data format is supported, the response will be decoded and accessible by iterating over the returned instance. When the format option is set, it will be used to select the decoder. If no format option is provided, an attempt is made to extract it from the response Content-Type header. This pattern is configurable with the format_regex option.

$api = new RestClient([
    'base_url' => "http://vimeo.com/api/v2", 
    'format' => "php"
]);
$result = $api->get("tcdent/info");
// GET http://vimeo.com/api/v2/tcdent/info.php
foreach($result as $key => $value)
    var_dump($value);

Reading via ArrayAccess has been implemented, too:

var_dump($result['id']);

To access the decoded response as an array, call decode_response().

'json' and 'php' formats are configured to use the built-in json_decode and unserialize functions, respectively. Overrides and additional decoders can be specified upon instantiation, or individually afterword. Decoder functions take one argument: the raw request body. Lambdas and functions created with create_function work, too.

function my_xml_decoder($data){
    new SimpleXMLElement($data);
}

$api = new RestClient([
    'format' => "xml", 
    'decoders' => ['xml' => "my_xml_decoder"]
]);

-or-

$api = new RestClient;
$api->set_option('format', "xml");
$api->register_decoder('xml', "my_xml_decoder");

Or, using a lambda; this particular example allows you to receive decoded JSON data as an array.

$api->register_decoder('json', function($data){
    return json_decode($data, TRUE);
});

Duplicate Headers and Parameters

When duplicate (repeated) HTTP headers are received, they are accessible via an indexed array referenced by the shared key. Duplicated headers and parameters may also be constructed in requests using the same format.

Example (unlikely) response:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Type: text/html; charset=UTF-8

Accessing repeated headers in the response instance:

$result = $api->get('/');
var_dump($result->headers->content_type);

=> ["text/html", "text/html; charset=UTF-8"]

Passing repeated headers and parameters in a request:

$result = $api->get('/', [
    'foo[]' => ['bar', 'baz']
], [
    'Accept' => ['text/json', 'application/json']
]);

Will create headers and a query string (GET) or response body (POST, etc) with the following content:

GET /?foo[]=bar&foo[]=baz HTTP/1.1
Accept: text/json
Accept: application/json

Multiple HTTP Status Lines

Multiple status lines returned in a single response payload are supported, and available as response_status_lines which is an indexed array populated on the response instance.

Example response with multiple status lines (truncated):

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Cache-Control: no-cache
...

$result = $api->get('/');
var_dump($result->response_status_lines);

=> ["HTTP/1.1 100 Continue", "HTTP/1.1 200 OK"]

JSON Verbs

This library will never validate or construct PATCH JSON content, but it can be configured to communicate well-formed data.

PATCH JSON content with correct content type:

$result = $api->execute("http://httpbin.org/patch", 'PATCH',
    json_encode([foo' => 'bar']), [
        'X-HTTP-Method-Override' => 'PATCH', 
        'Content-Type' => 'application/json-patch+json']);

Tests

The test package includes a simple server script which returns debug information for verifying functionality. Start the server first, then run tests:

$ php -S localhost:8888 RestClientTest.php
$ phpunit RestClientTest.php

Requires PHP > 5.5.7 in order for getallheaders data to populate.
If you specify an alternate port number or hostname to the PHP server you need to re-configure it in your phpunit.xml file:

<php><var name="TEST_SERVER_URL" value="http://localhost:8888"/></php>

tcdent / php-restclient

Maintainers

Details