Download the PHP package chroma-x/basic-http-client without Composer

PHP Basic HTTP Client

A basic yet extensible HTTP client library providing different authentication methods written in PHP.

What about PSR-7?

PHP Basic HTTP Client is an alternative to other very good implementations like Guzzle that are following the PSR-7 guidelines.

This project not follows these guidelines for different reasons.

1. PSR-7 is heavily over engineered due to also match complex edge cases.
2. Objects implementing the PSR-7 interfaces have to be immutable wich is resulting in an unusual API from the PHP dev point of view and an unneccessarily increased need of performance.

Find out more at the „PSR-7 is imminent, and here's my issues with it“ blog post by PHP-FIG member Evert Pot and this discussion at Stackoverflow.

Installation

Usage

Autoloading and namesapce

Simple usage

Preparing the HTTP client

Performing requests and read the response

Body-less requests (GET, HEAD and DELETE)

Perfoming the following GET request with additional query parameters

will result in the following HTTP request.

The same mechanic is offered to perform HEAD and DELETE requests wich all are body-less.

Body-full requests (POST, PUT, PATCH)

Perfoming the following POST request with body data

will result in the following HTTP request.

The same mechanic is offered to perform PUT and PATCH requests wich all are body-full.

Detailed usage

The following example shows the usage with a more detailed configuration.

Configuring an HTTP Transport instance

Configuring an HTTPS Transport instance

Configuring a Message instance with Body

Message and request Header instances

Please note, that headers have some unusual behaviours. Header names have an uniform way of nomenclature so the following three getter calls would have the same result.

To allow multiple request headers using the same name, the method addAdditionalHeader provides such a logic.

Configuring an endpoints URL, build the Request instance and perform the HTTP request

For more information about the usage of the URL object please take a look at the PHP URL Util project.

The resulting HTTP request would be the following.

Usage of authentication methods

You can add one or more Authentication instances to every Request instance. At the moment this project provides classes for HTTP Basic Authentication and SSL Client Certificate Authentication.

HTTP Basic Authentication

Required credentials are a username and a password that get provided to the class constructor as arguments.

SSL Client Certificate Authentication

Required credentials are a Certificate Authority Certificate, a Client Certificate and the password that is used to decrypt the Client Certificate that get provided to the class constructor as arguments.

Reading from the resulting Response object

Getting the response object

If using the BasicHttpClient the response object is returned by the termination methods listed above. If directly using the Request instance, you can get the Response object via a getter.

Getting effective Request information

After successful performing the request, the effective request information is tracked back to the Request object. They can get accessed as follows.

Getting some transactional statistics

Extending the Basic HTTP Client

Every part of the client is based upon proper interfaces. Most class instances can get injected into the client itself. If you want to extend the client just write some classes implementing the according interface and you´re done with that.

Take a look at the PHP JSON HTTP Client which is an extension of the PHP Basic HTTP Client.

Exception handling

PHP Basic HTTP Client provides different exceptions – also provided by the PHP Common Exceptions project – for proper handling.
You can find more information about PHP Common Exceptions at Github.

Exceptions to be expected

In general you should expect that any setter method could thrown an \InvalidArgumentException. The following exceptions could get thrown while using PHP Basic HTTP Client.

• ChromaX\CommonException\IoException\FileNotFoundException on configuring a ClientCertificateAuthenticationinstance
• ChromaX\CommonException\IoException\FileReadableException on configuring a ClientCertificateAuthenticationinstance
• ChromaX\BasicHttpClient\Exception\HttpRequestAuthenticationException on performing a request
• ChromaX\BasicHttpClient\Exception\HttpRequestException on performing a request
• ChromaX\CommonException\NetworkException\ConnectionTimeoutException on performing a request
• ChromaX\CommonException\NetworkException\CurlException on performing a request

Contribution

Contributing to our projects is always very appreciated.
But: please follow the contribution guidelines written down in the CONTRIBUTING.md document.

License

PHP Basic HTTP Client is under the MIT license.