README

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.

• Hermes
  • Install
  • Configuration
    • Channel configuration
    • Configure the guzzle option
    • Configure the guzzle handler
    • Configure the guzzle middleware
    • Customizing the guzzle handler stack
      • "Tap" class parameters
  • Middleware
    • RequestEvent
    • ResponseHandler
  • Usage
  • Change log
  • Testing
  • Contributing
  • Security
  • Credits
  • License

Install

You may use Composer to install Hermes into your Laravel project:

$ composer require jenky/hermes

After installing Hermes, publish its assets using the vendor:publish Artisan command.

php artisan vendor:publish

or

php artisan vendor:publish --provider="Jenky\Hermes\HermesServiceProvider"

Configuration

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.

Channel configuration

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.

Configure the guzzle option

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 the guzzle handler

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 the guzzle middleware

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 hermes config file. This is because those implementations are not yet bound to the container when the hermes config 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.

Customizing the guzzle handler stack

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 parameters

"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',
    ],
],

Middleware

RequestEvent

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;

ResponseHandler

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,
        // ...
    ],
],

json driver will automatically use Jenky\Hermes\Middleware\ResponseHandler middleware and set the default response_handler to Jenky\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;

Usage

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');

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email contact@lynh.me instead of using the issue tracker.

Credits

• Lynh
• All Contributors

License

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