Download the PHP package vanilla/garden-http without Composer

Garden HTTP

Garden HTTP is an unbloated HTTP client library for building RESTful API clients. It's meant to allow you to access people's APIs without having to copy/paste a bunch of cURL setup and without having to double the size of your codebase. You can use this library as is for quick API clients or extend the HttpClient class to make structured API clients that you use regularly.

Installation

Garden HTTP requires PHP 7.4 or higher and libcurl

Garden HTTP is PSR-4 compliant and can be installed using composer. Just add vanilla/garden-http to your composer.json.

Garden request and response objects are PSR-7 compliant as well.

Basic Example

Almost all uses of Garden HTTP involve first creating an HttpClient object and then making requests from it. You can see below a default header is also set to pass a standard header to every request made with the client.

Throwing Exceptions

You can tell the HTTP client to throw an exception on unsuccessful requests.

Exceptions will be thrown with a message indicating the failing response and structured data as well.

Basic Authentication

You can specify a username and password for basic authentication using the auth option.

Extending the HttpClient through subclassing

If you are going to be calling the same API over and over again you might want to extend the HttpClient class to make an API client that is more convenient to reuse.

Extending the HttpClient with middleware

The HttpClient class has an addMiddleware() method that lets you add a function that can modify the request and response before and after being sent. Middleware lets you develop a library of reusable utilities that can be used with any client. Middleware is good for things like advanced authentication, caching layers, CORS support, etc.

Writing middleware

Middleware is a callable that accepts two arguments: an HttpRequest object, and the next middleware. Each middleware must return an HttpResponse object.

You have to call $next or else the request won't be processed by the HttpClient. Of course, you may want to short circuit processing of the request in the case of a caching layer so in that case you can leave out the call to $next.

Example: Modifying the request with middleware

Consider the following class that implements HMAC SHA256 hashing for a hypothetical API that expects more than just a static access token.

This middleware calculates a new authorization header for each request and then adds it to the request. It then calls the $next closure to perform the rest of the request.

The HttpHandlerInterface

In Garden HTTP, requests are executed with an HTTP handler. The currently included default handler executes requests with cURL. However, you can implement the the HttpHandlerInterface however you want and completely change the way requests are handled. The interface includes only one method:

The method is supposed to transform a request into a response. To use it, just pass an HttpRequest object to it.

You can also use your custom handler with the HttpClient. Just pass it to the constructor:

Inspecting requests and responses

Sometimes when you get a response you want to know what request generated it. The HttpResponse class has an getRequest() method for this. The HttpRequest class has a getResponse() method for the inverse.

Exceptions that are thrown from HttpClient objects are instances of the HttpResponseException class. That class has getRequest() and getResponse() methods so that you can inspect both the request and the response for the exception. This exception is of particular use since request objects are created inside the client and not by the programmer directly.

Mocking for Tests

An HttpHandlerInterface implementation and utilities are provided for mocking requests and responses.

Setup

Mocking Requests

Response Sequences

Anywhere you can use a mocked HttpResponse you can also use a MockHttpSequence.

Each item pushed into the sequence will return exactly once. Once that response has been returned it will not be returned again.

If the whole sequence is exhausted it will return 404 responses.

Response Functions

You can make a mock dynamic by providing a callable.

Assertions about requests

Some utilities are provided to make assertions against requests that were made. This can be particularly useful with a wildcard response.