nimbly / shuttle
Simple PSR-18 HTTP client.
Installs: 1 368 480
Dependents: 6
Suggesters: 0
Security: 0
Stars: 3
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^7.4|^8.0
- ext-json: *
- nimbly/capsule: ^1.0
- psr/http-client: ^1.0
Requires (Dev)
- php-coveralls/php-coveralls: ^2.1
- phpunit/phpunit: ^9.0
- symfony/var-dumper: ^4.2
- vimeo/psalm: ^4.0
Suggests
- ext-curl: Use cURL library to make HTTP calls.
README
A simple PSR-18 HTTP client library.
Installation
composer require nimbly/shuttle
Features
- Responses create php://temp response body stream and swap to disk when necessary.
- cURL (default) and Stream Context handlers supported.
- Middleware support out of the box.
- Easy body transformations when creating requests with JsonBody, FormBody, and XmlBody helper classes.
Not features
- Asynchronous calls.
Making requests: The easy way
The quickest and easiest way to begin making requests in Shuttle is to use the HTTP method name:
use Shuttle\Shuttle; $shuttle = new Shuttle; $response = $shuttle->get("https://www.google.com"); $response = $shuttle->post("https://example.com/search", "Form data"));
Shuttle has built-in methods to support the major HTTP verbs: get, post, put, patch, delete, head, and options. However, you can make any HTTP verb request using the request method directly.
$response = $shuttle->request("connect", "https://api.example.com/v1/books");
Handling responses
Responses in Shuttle implement PSR-7 ResponseInterface and as such are streamable resources.
$response = $shuttle->get("https://api.example.com/v1/books"); echo $response->getStatusCode(); // 200 echo $response->getReasonPhrase(); // OK echo $response->isSuccessful(); // true $body = $response->getBody()->getContents();
Handling failed requests
Shuttle will throw a RequestException
by default if the request failed. This includes things like host name not found, connection timeouts, etc.
Responses with HTTP 4xx or 5xx status codes will not throw an exception and must be handled properly within your business logic.
Making requests: The PSR-7 way
If code reusability and portability is your thing, future proof your code by making requests the PSR-7 way. Remember, PSR-7 stipulates that Request and Response messages be immutable.
use Capsule\Request; use Capsule\Uri; use Shuttle\Shuttle; // Build Request message. $request = new Request; $request = $request ->withMethod("get") ->withUri(new Uri("https://www.google.com")) ->withHeader("Accept-Language", "en_US"); // Send the Request. $shuttle = new Shuttle; $response = $shuttle->sendRequest($request);
Shuttle client options
handler
Pass in the HTTP handler instance to be used for all requests. Defaults toCurlHandler
. See Handlers section for more information.base_url
The base URL to prepend to all requests.http_version
The default HTTP protocol version to use. Defaults to 1.1.headers
An array of key & value pairs to pass in with each request.middleware
An array of middleware instances to be applied to each request and response. See Middleware section for more information.debug
Enable or disable debug mode. Debug mode prints handler specific debug messages to STDOUT. Defaults to false.
Request bodies
An easy way to submit data with your request is to use the \Shuttle\Body\*
helper classes. These classes will automatically
transform the data, convert to a BufferStream, and set a default Content-Type header on the request.
The request bodies support are:
JsonBody
Converts an associative array into JSON, setsContent-Type
header toapplication/json
.FormBody
Converts an associative array into a query string, setsContent-Type
header toapplication/x-www-form-urlencoded
.XmlBody
Does no conversion of data, setsContent-Type
header toapplication/xml
.
To submit a JSON payload with a request:
use Shuttle\Body\JsonBody; $book = [ "title" => "Breakfast Of Champions", "author" => "Kurt Vonnegut", ]; $shuttle->post("https://api.example.com/v1/books", new JsonBody($book));