Download the PHP package tomb1n0/generic-api-client without Composer

Generic API Client

When developing integrations for my PHP applications, i've often found myself carrying very similar but slightly different boiler-plate code around with me.

Often, each implementation will need:

• Some way of handling auth.
  • Often is as simple as adding an extra header or property to the body of the request.
• Pagination handling
  • Often boils down to checking for the presence of a header or some property in the body of the response, before fetching the next page with an added header/query parameter.
• Response Mocking
  • Providing confidence that our integration is working as we expected, and error conditions are properly handled.

There's also the question of what HTTP client to use, with the introduction of PSR-7, PSR-17 and PSR-18 we are able to depend on HTTP clients and factories that implement these interfaces rather than relying on any one client.

My goal with this package is to provide a wrapper around these PSR interfaces that makes it simpler to write API integrations.

Installation

Please note that this package does not require a HTTP client out of the box - but rather it depends on the virtual packages psr/http-client-implementation and psr/http-factory-implementation. This allows the package to be client-agnostic.

If you're unsure on this, i would recommend requiring guzzlehttp/guzzle alongside this package as it provides implementations for the above virtual packages.

If your project already require a HTTP-client that has implementations for the above standards, you can omit the guzzle dependency.

Usage

Please note that the examples below assume the use of Guzzle for the PSR-18 Client etc. Feel free to swap these out with your own.

Client Instantiation:

Making a JSON request:

Making a Form (x-www-form-urlencoded) request:

Making a request using a PSR-7 request directly

Configuration

Base Url:

Note that if you try to perform a request to a fully-formed URL that is different to the Base URL, the Base URL is ignored.

Pagination

You can create a pagination handler by creating a class that implements the PaginationHandlerContract interface provided by this package.

Middleware

Middleware can be created by creating a class that implements the MiddlewareContract interface.

Note that it is possible for a middleware to mutate the request before it is sent, or the response after it is received.

Testing the API

Stubbing Responses

It is possible to stub responses for testing purposes:

Preventing Stray Requests

By default the library will return a 200 OK for any non-matched responses when faked. If you prefer, you can prevent stray requests:

Asserting Requests

Maybe you want to assert the correct payload is sent to an API to create a user:

Asserting Requests With Custom Request Matching

Maybe you want to stub a response using some other information in the request

Do the same as above but use the stubResponseWithCustomMatcher method providing a custom implementation of the matcher contract. For example you could use the included UrlMatcher to check the method type

Running the Tests

Credits

• Tom Harper
• All Contributors

License

The MIT License (MIT). Please see License File for more information.