The package provides a nice and easy wrapper around Guzzle for use in your Laravel applications. If you don't know what Guzzle does, take a peek at their intro. Shortly said, Guzzle is a PHP HTTP client that makes it easy to send HTTP requests and trivial to integrate with web service.
You may use Composer to install Hermes into your Laravel project:
$ composer require jenky/hermesAfter installing Hermes, publish its assets using the vendor:publish Artisan command.
php artisan vendor:publishor
php artisan vendor:publish --provider="Jenky\Hermes\HermesServiceProvider"After publishing Hermes's assets, its primary configuration file will be located at config/hermes.php. This configuration file allows you to configure your guzzle client options and each configuration option includes a description of its purpose, so be sure to thoroughly explore this file.
A channel is simply a guzzle http client instance with its own configuration. This allows you to create a http client on the fly and reuse anytime, anywhere you want.
Set guzzle request options within the channel. Please visit Request Options for more information.
'default' => [
'options' => [
'base_uri' => 'https://api.github.com/v3/',
'time_out' => 20,
],
],Configure guzzle Handler within the channel.
By default, guzzle will choose the most appropriate handler based on the extensions available on your system. However you can override this behavior with handler option. Optionally, any constructor parameters the handler needs may be specified using the with configuration option:
'default' => [
'handler' => App\Http\CustomCurlHandler::class,
'with' => [
'delay' => 5,
],
],An alternative way is set the handler in the options configuration:
'default' => [
'options' => [
'handler' => App\Http\CustomCurlHandler::create(['delay' => 5]),
],
],Configure guzzle Middleware within the channel.
'default' => [
'middleware' => [
Jenky\Hermes\Middleware\RequestEvent::class,
],
],You can read about the middleware in the middleware section.
Do no attempt to resolve container binding implementations such as config, session driver, logger inside the
hermesconfig file. This is because those implementations are not yet bound to the container when thehermesconfig is loaded.
'middleware' => [
// This won't work properly
GuzzleHttp\Middleware::log(logs(), new GuzzleHttp\MessageFormatter),
],Instead of using middleware in config, consider customizing the guzzle handler stack if you needs container binding implementations.
Sometimes you may need complete control over how guzzle's HandleStack is configured for an existing channel. For example, you may want to add, remove or unshift a middleware for a given channel's handler stack.
To get started, define a tap array on the channel's configuration. The tap array should contain a list of classes that should have an opportunity to customize (or "tap" into) the handle stack instance after it is created:
'default' => [
'tap' => [
App\Http\Client\CustomizeHandlerStack::class,
],
],Once you have configured the tap option on your channel, you're ready to define the class that will customize your HandlerStack instance. This class only needs a single method: __invoke, which receives an GuzzleHttp\HandlerStack instance.
<?php
namespace App\Http\Client;
use Psr\Http\Message\RequestInterface;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
class CustomizeHandlerStack
{
/**
* Customize the given handler stack instance.
*
* @param \GuzzleHttp\HandlerStack $stack
* @return void
*/
public function __invoke(HandlerStack $stack)
{
$stack->before('add_foo', Middleware::mapRequest(function (RequestInterface $request) {
return $request->withHeader('X-Baz', 'Qux');
}, 'add_baz');
}
}All of your "tap" classes are resolved by the service container, so any constructor dependencies they require will automatically be injected.
"Tap" class can also receive additional parameters. For example, if your handler needs to log the Guzzle request and response by using a specific Laravel logger channel, you could create a LogMiddleware class that receives a channel name as an additional argument.
Additional parameters will be passed to the class after the $stack argument:
<?php
namespace App\Support;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\MessageFormatter;
use GuzzleHttp\Middleware;
use Illuminate\Log\LogManager;
class LogMiddleware
{
/**
* The logger manager instance.
*
* @var \Illuminate\Log\LogManager
*/
protected $logger;
/**
* Create new log middleware instance.
*
* @param \Illuminate\Log\LogManager $logger
* @return void
*/
public function __construct(LogManager $logger)
{
$this->logger = $logger;
}
/**
* Customize the given handle stack instance.
*
* @param \GuzzleHttp\HandlerStack $stack
* @return void
*/
public function __invoke(HandlerStack $stack, ?string $channel = null, string $level = 'debug')
{
$stack->push(Middleware::log(
$this->logger->channel($channel), new MessageFormatter, $level
));
}
}"Tap" class parameters may be specified in hermes config by separating the class name and parameters with a :. Multiple parameters should be delimited by commas:
'default' => [
'tap' => [
App\Http\Client\LogMiddleware::class.':slack',
],
],This middleware will fire Jenky\Hermes\Events\RequestHandled event when a request had been fulfilled. It has these properties:
/**
* The request instance.
*
* @var \Psr\Http\Message\RequestInterface
*/
public $request;
/**
* The response instance.
*
* @var \Psr\Http\Message\ResponseInterface|null
*/
public $response;
/**
* The request options.
*
* @var array
*/
public $options;When sending the request, GuzzleHttp\Psr7\Response will be used as the default response handler. However you can configure the request options to use your own response handler. Please note that response handler must be an instance of Psr\Http\Message\ResponseInterface
'default' => [
'driver' => 'guzzle',
'options' => [
'base_uri' => 'https://httpbin.org/',
// ...
'response_handler' => Jenky\Hermes\JsonResponse::class,
],
'middleware' => [
Jenky\Hermes\Middleware\ResponseHandler::class,
// ...
],
],
jsondriver will automatically useJenky\Hermes\Middleware\ResponseHandlermiddleware and set the defaultresponse_handlertoJenky\Hermes\JsonResponse
Now your HTTP request will returns an instance of Jenky\Hermes\JsonResponse instead of GuzzleHttp\Psr7\Response which provides a variety of methods that may be used to inspect the response:
$response->isSuccessful(): bool;
$response->isError(): bool;
$response->isInformational(): bool;
$response->isRedirect(): bool;
$response->isClientError(): bool;
$response->isServerError(): bool;
$response->ok(): bool;
$response->created(): bool;
$response->badRequest(): bool;
$response->unauthorized(): bool;
$response->forbidden(): bool;
$response->notFound(): bool;
$response->unprocessable(): bool;
$response->serverError(): bool;
$response->header(?string $header = null, $default = null): mixed;
$response->status($code = null);
$response->body(): string;
$response->toArray(): array;
$response->toJson(): string;
$response->exists($key): bool;
$response->get($key, $default = null): mixed;The Jenky\Hermes\JsonResponse object also implements the PHP ArrayAccess interface and support magic __get method, allowing you to access JSON response data directly on the response:
$response['name'];
// or
$response->name;use Jenky\Hermes\Facades\Guzzle;
Guzzle::get('https://jsonplaceholder.typicode.com/users');
// or using helper
guzzle()->get('https://jsonplaceholder.typicode.com/users');Sometimes you may wish to send a request to a channel other than your application's default channel. You may use the channel method on the Guzzle facade to retrieve and send to any channel defined in your configuration file:
use Jenky\Hermes\Facades\Guzzle;
Guzzle::channel('my_channel')->get('https://jsonplaceholder.typicode.com/users');
// or using helper
guzzle('my_channel')->get('https://jsonplaceholder.typicode.com/users');Please see CHANGELOG for more information on what has changed recently.
$ composer testPlease see CONTRIBUTING and CODE_OF_CONDUCT for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.