Download the PHP package phpro/http-tools without Composer

HTTP-Tools

The goal of this package is to provide you some tools to set-up a data-centric, consistent HTTP integration. The HTTP client implementation you want to use is just a small implementation detail and doesn't matter. However, here are some default guidelines:

Prerequisites

Choosing what HTTP package you want to us is all up to you. We do require a PSR implementations in order to install this package:

• PSR-7: psr/http-message-implementation like nyholm/psr7 or guzzlehttp/psr7
• PSR-17: psr/http-factory-implementation like nyholm/psr7 or guzzlehttp/psr7
• PSR-18: psr/http-client-implementation like symfony/http-client or guzzlehttp/guzzle

Installation

Setting up an HTTP client :

You can choose whatever HTTP client you want. However, this package provides some convenient factories that make the configuration a bit easier.

The factory accepts a list of implementation specific plugins / middlewares. Besides that, you can configure implementation-specific options like a base_uri or default headers.

You can always create your own factory if you want to have more control or want to use another tool!

Note: This package does not download a specific HTTP implementation. You can choose whatever package you want, but you'll have to manually add it to composer.

Configuring the client through plugins

Plugin-Middleware : Patato-Patato.

If you want to extend how an HTTP client works, we want you to use plugins! You can use plugins for everything: logging, authentication, language specification, ...

Examples:

Built-in plugins:

• AcceptLanguagePlugin: Makes it possible to add an Accept-Language to a request.
• CallbackPlugin: Makes it possible to promote a simple callable into a real Plugin.

Remember: There are a shitload of HTTPlug middleware available already. Try on of them before writing your own one!

Logging

This package contains the php-http/logger-plugin. On top of that, we've added some decorators that help you strip out sensitive information from the logs. You can switch from full to simple logging by specifying a debug parameter!

More info ...

Using the HTTP-Client

We don't want you to use the PSR-18 client directly! Instead, we suggest you to use a request handler principle. So what does this architecture look like?

• Models: Request / Response value objects that can be used as wrapper around the outgoging or incoming data (arrays, objects, strings, ...).
• RequestHandler: Transform a request data model into a response data model by using a transport. You could add error handling in there as well.
• Transport: Transforms a Request data model into a PSR-7 HTTP request and asks for a response through the actual HTTP client.
• Encoding: A transport can take encoders / decoders that are responsible for converting the value objects data to e.g. JSON payloads and visa versa.
• HTTP-Client: Whichever PSR-18 HTTP client you want to use: guzzle, curl, symfony/http-client, ...

More information on Transports and Encodings

By using this architecture, we provide an easy to extend flow with models that replace cumbersome array structures.

You might be familiar with 1 "client" class that provides access to multiple API endpoints. We see that approach as a multi-requesthandler class. You are free to choose that approach, owever, we suggest using 1 request handler per API endpoint. This way, you can inject / mock only the things you require at that moment into your codebase.

Example implementation:

Example request handler:

This example is rather easy and might seem like overkill at first. The true power will be visible once you create multiple named constructors and conditional porperty accessors inside the request models. The response models, if crafted carefully, will improve the stability of your integration!

Async request handlers

In order to send async requests, you can use this package in combination with fiber-based PSR-18 clients. The architecture can remain as is.

An example client based on ReactPHP might be based on this:

(There currently is no official fiber based PSR-18 implementation of either AMP or ReactPHP. Therefore, a small bridge can be used intermediately)

Since fibers deal with the async part, you can write your Request handlers is if they were synchronous:

In order to fetch multiple simultaneous requests, you can execute these in parallel:

If your client is fiber compatible, this will fetch all requests in parallel. If your client is not fiber compatible, this will result in the requests being performed in series.

SDK

In some situations, writing request handlers might be overkill. This package also provides some tools to compose a more generic API client instead. However, our primary suggestion is to create specific request handlers instead!

More information on creating SDKs

Testing HTTP clients

This tool provided some traits for unit testing your API client with PHPUnit.

UseHttpFactories

This trait can help you build requests and responses inside your tests without worrying what HTTP package you use:

• createRequest
• createResponse
• createStream
• createEmptyHttpClientException

UseHttpToolsFactories

This trait can help you build HTTP tools specific objects in unit tests. It could be hande to e.g. test transports.

• createToolsRequest

Example:

UseMockClient

Includes UseHttpFactories trait

Preferably, this one will be used to test your own middlewares and transports. It is also possible to test a request-handler, but you'll have to manually provide the response for it.

example:

More info ...

UseVcrClient

Includes UseHttpFactories trait

This one can be used to test your request-handlers with realtime data. The first you use it in your test, it will do the actual HTTP request. The response of this request will be recorded and stored inside your project. The second time the test runs, it will use the recorded version.

example:

More info ...