{"id":23882289,"url":"https://github.com/jenky/hermes","last_synced_at":"2026-05-14T21:06:35.713Z","repository":{"id":56997981,"uuid":"183476491","full_name":"jenky/hermes","owner":"jenky","description":"A Guzzle manager for your Laravel app","archived":false,"fork":false,"pushed_at":"2021-07-07T09:19:28.000Z","size":128,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-10T01:13:42.849Z","etag":null,"topics":["guzzle","guzzle-middleware","guzzlehttp","http-message","laravel","psr-7"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-25T17:01:29.000Z","updated_at":"2020-12-11T03:42:32.000Z","dependencies_parsed_at":"2022-08-21T14:50:18.662Z","dependency_job_id":null,"html_url":"https://github.com/jenky/hermes","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/jenky/hermes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhermes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhermes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhermes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhermes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenky","download_url":"https://codeload.github.com/jenky/hermes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenky%2Fhermes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33043298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guzzle","guzzle-middleware","guzzlehttp","http-message","laravel","psr-7"],"created_at":"2025-01-04T02:53:11.890Z","updated_at":"2026-05-14T21:06:35.698Z","avatar_url":"https://github.com/jenky.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes\n\n[![Latest Version on Packagist][ico-version]][link-packagist]\n[![Test Status][ico-gh-tests]][link-gh-tests]\n[![Quality Score][ico-code-quality]][link-code-quality]\n[![Codecov][ico-codecov]][link-codecov]\n[![Total Downloads][ico-downloads]][link-downloads]\n[![Software License][ico-license]](LICENSE.md)\n\nThe 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](http://docs.guzzlephp.org/en/stable/index.html). Shortly said, Guzzle is a PHP HTTP client that makes it easy to send HTTP requests and trivial to integrate with web service.\n\n- [Hermes](#hermes)\n  - [Install](#install)\n  - [Configuration](#configuration)\n    - [Channel configuration](#channel-configuration)\n    - [Configure the guzzle option](#configure-the-guzzle-option)\n    - [Configure the guzzle handler](#configure-the-guzzle-handler)\n    - [Configure the guzzle middleware](#configure-the-guzzle-middleware)\n    - [Customizing the guzzle handler stack](#customizing-the-guzzle-handler-stack)\n      - [\"Tap\" class parameters](#tap-class-parameters)\n  - [Middleware](#middleware)\n    - [`RequestEvent`](#requestevent)\n    - [`ResponseHandler`](#responsehandler)\n  - [Usage](#usage)\n  - [Change log](#change-log)\n  - [Testing](#testing)\n  - [Contributing](#contributing)\n  - [Security](#security)\n  - [Credits](#credits)\n  - [License](#license)\n\n## Install\n\nYou may use Composer to install Hermes into your Laravel project:\n\n``` bash\n$ composer require jenky/hermes\n```\n\nAfter installing Hermes, publish its assets using the `vendor:publish` Artisan command.\n\n``` bash\nphp artisan vendor:publish\n```\n\nor\n\n``` bash\nphp artisan vendor:publish --provider=\"Jenky\\Hermes\\HermesServiceProvider\"\n```\n\n## Configuration\n\nAfter 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.\n\n### Channel configuration\n\nA 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.\n\n### Configure the guzzle option\n\nSet guzzle request options within the channel. Please visit [Request Options](http://docs.guzzlephp.org/en/stable/request-options.html) for more information.\n\n``` php\n'default' =\u003e [\n    'options' =\u003e [\n        'base_uri' =\u003e 'https://api.github.com/v3/',\n        'time_out' =\u003e 20,\n    ],\n],\n```\n\n### Configure the guzzle handler\nConfigure guzzle [Handler](http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html#handlers) within the channel.\n\nBy 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:\n\n``` php\n'default' =\u003e [\n    'handler' =\u003e App\\Http\\CustomCurlHandler::class,\n    'with' =\u003e [\n        'delay' =\u003e 5,\n    ],\n],\n```\n\nAn alternative way is set the handler in the [`options`](#configure-the-guzzle-option) configuration:\n\n``` php\n'default' =\u003e [\n    'options' =\u003e [\n        'handler' =\u003e App\\Http\\CustomCurlHandler::create(['delay' =\u003e 5]),\n    ],\n],\n```\n\n### Configure the guzzle middleware\n\nConfigure guzzle [Middleware](http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html#middleware) within the channel.\n\n``` php\n'default' =\u003e [\n    'middleware' =\u003e [\n        Jenky\\Hermes\\Middleware\\RequestEvent::class,\n    ],\n],\n```\n\nYou can read about the middleware in the [middleware](#middleware) section.\n\n\u003e 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.\n\n``` php\n'middleware' =\u003e [\n    // This won't work properly\n    GuzzleHttp\\Middleware::log(logs(), new GuzzleHttp\\MessageFormatter),\n],\n```\n\n\u003e Instead of using middleware in config, consider [customizing the guzzle handler stack](#customizing-the-guzzle-handler-stack) if you needs container binding implementations.\n\n### Customizing the guzzle handler stack\n\nSometimes you may need complete control over how guzzle's [HandleStack](http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html#handlerstack) 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.\n\nTo 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:\n\n``` php\n'default' =\u003e [\n    'tap' =\u003e [\n        App\\Http\\Client\\CustomizeHandlerStack::class,\n    ],\n],\n```\n\nOnce 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.\n\n``` php\n\u003c?php\n\nnamespace App\\Http\\Client;\n\nuse Psr\\Http\\Message\\RequestInterface;\nuse GuzzleHttp\\HandlerStack;\nuse GuzzleHttp\\Middleware;\n\nclass CustomizeHandlerStack\n{\n    /**\n     * Customize the given handler stack instance.\n     *\n     * @param  \\GuzzleHttp\\HandlerStack  $stack\n     * @return void\n     */\n    public function __invoke(HandlerStack $stack)\n    {\n        $stack-\u003ebefore('add_foo', Middleware::mapRequest(function (RequestInterface $request) {\n            return $request-\u003ewithHeader('X-Baz', 'Qux');\n        }, 'add_baz');\n    }\n}\n```\n\n\u003e All of your \"tap\" classes are resolved by the service container, so any constructor dependencies they require will automatically be injected.\n\n#### \"Tap\" class parameters\n\n\"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.\n\nAdditional parameters will be passed to the class after the `$stack` argument:\n\n``` php\n\u003c?php\n\nnamespace App\\Support;\n\nuse GuzzleHttp\\HandlerStack;\nuse GuzzleHttp\\MessageFormatter;\nuse GuzzleHttp\\Middleware;\nuse Illuminate\\Log\\LogManager;\n\nclass LogMiddleware\n{\n    /**\n     * The logger manager instance.\n     *\n     * @var \\Illuminate\\Log\\LogManager\n     */\n    protected $logger;\n\n    /**\n     * Create new log middleware instance.\n     *\n     * @param  \\Illuminate\\Log\\LogManager $logger\n     * @return void\n     */\n    public function __construct(LogManager $logger)\n    {\n        $this-\u003elogger = $logger;\n    }\n\n    /**\n     * Customize the given handle stack instance.\n     *\n     * @param  \\GuzzleHttp\\HandlerStack $stack\n     * @return void\n     */\n    public function __invoke(HandlerStack $stack, ?string $channel = null, string $level = 'debug')\n    {\n        $stack-\u003epush(Middleware::log(\n            $this-\u003elogger-\u003echannel($channel), new MessageFormatter, $level\n        ));\n    }\n}\n```\n\n\"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:\n\n``` php\n'default' =\u003e [\n    'tap' =\u003e [\n        App\\Http\\Client\\LogMiddleware::class.':slack',\n    ],\n],\n```\n\n## Middleware\n\n### `RequestEvent`\n\nThis middleware will fire `Jenky\\Hermes\\Events\\RequestHandled` event when a request had been fulfilled. It has these properties:\n\n``` php\n/**\n * The request instance.\n *\n * @var \\Psr\\Http\\Message\\RequestInterface\n */\npublic $request;\n\n/**\n * The response instance.\n *\n * @var \\Psr\\Http\\Message\\ResponseInterface|null\n */\npublic $response;\n\n/**\n * The request options.\n *\n * @var array\n */\npublic $options;\n```\n\n### `ResponseHandler`\n\nWhen 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`\n\n``` php\n'default' =\u003e [\n    'driver' =\u003e 'guzzle',\n    'options' =\u003e [\n        'base_uri' =\u003e 'https://httpbin.org/',\n        // ...\n        'response_handler' =\u003e Jenky\\Hermes\\JsonResponse::class,\n    ],\n    'middleware' =\u003e [\n        Jenky\\Hermes\\Middleware\\ResponseHandler::class,\n        // ...\n    ],\n],\n```\n\n\u003e `json` driver will automatically use `Jenky\\Hermes\\Middleware\\ResponseHandler` middleware and set the default `response_handler` to `Jenky\\Hermes\\JsonResponse`\n\nNow 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:\n\n``` php\n$response-\u003eisSuccessful(): bool;\n$response-\u003eisError(): bool;\n$response-\u003eisInformational(): bool;\n$response-\u003eisRedirect(): bool;\n$response-\u003eisClientError(): bool;\n$response-\u003eisServerError(): bool;\n$response-\u003eok(): bool;\n$response-\u003ecreated(): bool;\n$response-\u003ebadRequest(): bool;\n$response-\u003eunauthorized(): bool;\n$response-\u003eforbidden(): bool;\n$response-\u003enotFound(): bool;\n$response-\u003eunprocessable(): bool;\n$response-\u003eserverError(): bool;\n$response-\u003eheader(?string $header = null, $default = null): mixed;\n$response-\u003estatus($code = null);\n$response-\u003ebody(): string;\n\n$response-\u003etoArray(): array;\n$response-\u003etoJson(): string;\n$response-\u003eexists($key): bool;\n$response-\u003eget($key, $default = null): mixed;\n```\n\nThe `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:\n\n``` php\n$response['name'];\n// or\n$response-\u003ename;\n```\n\n## Usage\n\n``` php\nuse Jenky\\Hermes\\Facades\\Guzzle;\n\nGuzzle::get('https://jsonplaceholder.typicode.com/users');\n// or using helper\nguzzle()-\u003eget('https://jsonplaceholder.typicode.com/users');\n```\n\nSometimes 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:\n\n``` php\nuse Jenky\\Hermes\\Facades\\Guzzle;\n\nGuzzle::channel('my_channel')-\u003eget('https://jsonplaceholder.typicode.com/users');\n// or using helper\nguzzle('my_channel')-\u003eget('https://jsonplaceholder.typicode.com/users');\n```\n\n## Change log\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Testing\n\n``` bash\n$ composer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.\n\n## Security\n\nIf you discover any security related issues, please email contact@lynh.me instead of using the issue tracker.\n\n## Credits\n\n- [Lynh][link-author]\n- [All Contributors][link-contributors]\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[ico-version]: https://img.shields.io/packagist/v/jenky/hermes.svg\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg\n[ico-travis]: https://img.shields.io/travis/com/jenky/hermes/master.svg\n[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/jenky/hermes.svg\n[ico-code-quality]: https://img.shields.io/scrutinizer/g/jenky/hermes.svg\n[ico-downloads]: https://img.shields.io/packagist/dt/jenky/hermes.svg\n[ico-gh-tests]: https://github.com/jenky/hermes/workflows/Tests/badge.svg\n[ico-codecov]: https://codecov.io/gh/jenky/hermes/branch/master/graph/badge.svg\n\n[link-packagist]: https://packagist.org/packages/jenky/hermes\n[link-travis]: https://travis-ci.com/jenky/hermes\n[link-scrutinizer]: https://scrutinizer-ci.com/g/jenky/hermes/code-structure\n[link-code-quality]: https://scrutinizer-ci.com/g/jenky/hermes\n[link-downloads]: https://packagist.org/packages/jenky/hermes\n[link-author]: https://github.com/jenky\n[link-contributors]: ../../contributors\n[link-gh-tests]: https://github.com/jenky/hermes/actions\n[link-codecov]: https://codecov.io/gh/jenky/hermes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenky%2Fhermes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenky%2Fhermes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenky%2Fhermes/lists"}