Download the PHP package pluggit/http-client without Composer

Pluggit Http

Small PSR7 compatible library to perform http requests based on pre-configured set of requests

TL;DR

Table of contents

• Installation
• Requirements
  • Optional requirements
  • Additional requirements
• Compatibility
• Usage
  • Defining a configuration
  • Building the client
  • Creating a request
  • Sending the request
  • Exceptions
• REST API integration example
  • Building the API client
  • Get a user
  • Create a user
  • Replace a user
  • Update a user
  • Delete a user
• Annexes
  • Pimple Service Provider
  • Development environment

Installation

Require the package as usual

To use Guzzle as a sender (the default option), you have to require it manually

Requirements

• php >=5.5
• guzzlehttp/psr7 ^1.0
• psr/log ^1.0

Note: This package relies on the implementation of guzzle for the PSR-7: HTTP message interfaces

Additional requirements

Guzzle

The library allows to use different senders to execute requests; and adapter for guzzlehttp/guzzle it's included in the library but you must require the dependency manually

Optional requirements

Yaml parsing

If you want to use a Yaml file as a configuration source you can: a) Use you own parser and pass the config as an array b) Require symfony/yaml as dependency and pass the yaml filepath to the builder

Logging

Do you want to know why your request is failing? No problem, the library accepts any Psr-3 logger logger implementation (like Monolog) to write debug and error messages.

For a quick start you can use Symfony's console package to have debug messages in the console

You will now be able to activate the console debug mode

Pimple

If you use pimple for building your dependencies you can use the provider Cmp\Http\Provider\HttpClientServiceProvider to register the multi client.

NOTE: See the annex for how to register the provider

Compatibility

This library has been tested with the following PHP versions and setups

Usage

The library allows to build requests from a set configuration values, execute them trough the client and get a response

Defining a configuration

The configuration is what tells the client how to build the requests, let's see some examples of configuration

The first line defines a name for a service, in this case my_users_api

NOTE: You can see a full-fledged sample configuration file in config-sample/requests.yaml for working with a REST API

Service configuration values

• endpoint (required): This is the endpoint for the all the request for this service
• headers: A key-value array with the headers to add to all the requests for this service
• query: A key-value array with the query parameters to append in the URI of all the requests for this service
• body: A key-value array with the post parameters to send in the body of all the requests for this service
• version: HTTP protocol version, default one 1.1
• options: A key-value array with options to pass to the http client sender to modify it's behaviour
• requests: A key-value array with the allowed requests for this service

Request configuration values

The request configuration allows the set almost the same options as the service configuration, overwriting the values provided for the service, this allows to define a general behaviour for a service but tweak some options for specific requests, like for example, allowing a longer timeout

• path (required): Defines the path that follows the endpoint
• method: Defines the HTTP method for the request. GET by default
• headers: A key-value array with the headers to add to this request
• query: A key-value array with the query parameters to append in the URI of this request
• body: A key-value array with the post parameters to send in the body of this request
• version: HTTP protocol version, default one 1.1
• options: A key-value array with options to pass to the http client sender to modify it's behaviour

Underlying client options

The request options allows to customize the client behaviour without the library having to know specific details about how to handle them.

Taking the provided integration with Guzzle as examples, we could have:

• Basic auth: auth: ['myUser', 'myPass']
• Timeout: timeout: 2
• Connect timeout: timeout: 15
• Add a certificate: ['cert' => ['/path/server.pem', 'password']]

Configuration placeholders

The library allows to indicate the presence of dynamic values in this configuration parameters as placeholders

Placeholder rules

• Placeholders are allowed in path, query, headers and body only
• Use this format to add a placeholder: ${PLACEHOLDER_NAME}
• Placeholders tag names must be uppercase (although lowercase keys can be used when replacing them)
• You can have the same placeholder multiple times across all options, it will be replaced in all of them.

Replacing a placeholder in the request

To replace the placeholders, pass the values as paramters when creating the request

Configuring the builder

The builder (Cmp\Http\ClientBuilder) is an object that will help you create you client, easing the customization process. This are the options available:

Once you've configured the builder you're ready to create clients for your http services

Building the client

There are 2 different clients that allow to create and execute requests:

• Cmp\Http\Client\MultiClientInterface: This client has access to all services
• Cmp\Http\Client\ServiceClientInterface: This client can execute request from a single service only

NOTE: You should try to inject always a ServiceClientInterface in your services, this will prevent sideeffects triggering requests from other services by mistake

The available methods in the clients are:

• create: Creates a request (Cmp\Http\Message\Request)
• send: Sends a request returning a Cmp\Http\Message\Response

They also provide some shortcuts to ease the use:

• execute: Creates and sends a request in a single call
• json: Creates and sends a request parsing a json response
• jsonAsArray: Creates and sends a request parsing as an array from a json response

Building a multi client

The easiest way to built the client is to use the method build on the builder

Building a service client

To build a service client specify the name of the service when building the client in the last step of the builder

Customizing the builds

The client require 3 dependencies to work, the builder has methods to override all of them with custom implementations

Sender

This is the class that sends the requests, it has to implement the Cmp\Http\Sender\SenderInterface and return a Psr-7 compatible response

The builder will try to use the provided Cmp\Http\Sender\GuzzleSender by default, to specify a different one use:

Even if you want to use guzzle, ou can also customize the internal client used

Config

This is the only required dependency, a configuration defining the available the requests

If symfony/yaml is installed, you can pass a filepath with a yaml configuration

Logger

You can pass a Psr\Log\LoggerInterface to receive debug and error messages

If you want to debug the raw http request/responses in the console you can activate the debug output in the builder (You'll need to have symfony/console installed)

Creating a request

To create a request you need to identify the service and the request that you want. Additionally you can pass dynamic values to substitute placeholders

The requests created are Cmp\Http\Message\Request intances, implementing Psr\Http\Message\RequestInterface, making them suitable to share between libraries and frameworks

The library request object provides some helpers to work with them in an easier way:

• withQueryParameter($key, $value): Allows you to add or modify a query parameter
• withPost(array $params): Allows to pass a key-value array of params to send as body
• withJsonPost(array $params): Allows to pass a key-value array of params; it will be codified as json and, the header Content-Type: application/json will be added
• __toString(): This makes the request embeddable in string

Customising the request creation

If you provide a request factory to the builder that complais with Cmp\Http\RequestFactoryInterface, you'll be able to extend the Request class and change the behaviour.

You may ask "hey, why would I like to do this for?"

For example to:

• Change all outgoing endpoints to a dummy server to prevent to executed certain requests on test environments
• Apply a configuration to all requests from all services

Sending the request

After sending the request you'll receive a Cmp\Http\Message\Response instance compatible with Psr\Http\Message\ResponseInterface

This response object also provides some helper methods:

• json($asArray = true): Parses the body as a json an returns either a stdClass object or an array
• jsonAsArray(): Same as before, but forcing the return type to be an array
• __toString(): This makes the response embeddable in string

Exceptions

Not everything works as expected; to make your life easier handling this, the library provides a small set of exceptions:

• Cmp\Http\Exception\RuntimeException: This is the base exception used in the library, all the exceptions thrown within the library code uses or extends this one
• Cmp\Http\Exception\RequestBuildException: This exception is thrown when the process of building a request cannot be completed
• Cmp\Http\Exception\RequestExecutionException: This exception is thrown when some error happens sending the request

REST API integration example

I'm going to show you how to perform the most common operation in a REST API.
Lets imagine that we want to interact with an API endpoint to manage our application users. The user entity looks like:

Now let's define the typical requests in our configuration file

Building the API client

Let's build a service client for our api, as per the configuration, all the requests will include a basic authentication

List users

This call would return an array of users

Get a user

This call will inject the user id in the path of the uri to request the user

Create a user

Here we're going to replace the placeholders in the body array, if the api only accepts a json body, we have to add the correct content type header, like in the example so the request is created correctly

Replace a user

We can replace placeholders in both path or body params at the same time

Update a user

When we update some fields only, we don't known in advance what fields we are going to send, so it's better to decide later

Delete a user

Deleting a user is even easier

Annexes

Pimple Service Provider

The library includes a service provider for Pimple to register a client in an easy way: Cmp\Http\Provider\HttpClientServiceProvider The provider will register the builder Cmp\Http\ClientBuilder object at key http_client.builder and a general purpouse multi-client Cmp\Http\Client\MultiClient in http_client.client, but it also accepts alias for both services

The options that the provider accepts are:

• http_client.yaml: A filepath with a ymal configuration file
• http_client.config: A configuration array with the requests
• http_client.logger: Pass a Psr\Logger\LoggerInterface object to add logging to the client
• http_client.sender: A custom implementation of the Cmp\Http\Sender\SenderInterface interface
• http_client.guzzle: A custom GuzzleHttp\ClientInterface object (useful to keep a reference)
• http_client.factory: A custom Cmp\Http\RequestFactoryInterface implementation
• http_client.debug: Pass true and this will activate console output for debugging

Development environment

To build the test environment you'll need docker and docker-compose installed:

Running the tests

You can run the tests only for a php version like this

Code-coverage

You can build a report for code coverage in HTML format. It will be available in bin/code-coverage

Stop the environment

Delete the environment

You can delete the docker images for a total clean-up