jenky / transmit
Laravel HTTP client manager
Requires
- php: ^7.2.5|^8.0
- guzzlehttp/guzzle: ^6.3|^7.0
- illuminate/config: ^7.0|^8.0|^9.0
- illuminate/container: ^7.0|^8.0|^9.0
- illuminate/http: ^7.0|^8.0|^9.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- orchestra/testbench: ^5.0|^6.0|^7.0
- phpunit/phpunit: ^8.0|^9.0
README
This package allows you to quickly create Http client with pre-defined configurations.
Install
You may use Composer to install Transmit into your Laravel project:
$ composer require jenky/transmit
After installing Transmit, publish its assets using the vendor:publish
Artisan command.
php artisan vendor:publish
or
php artisan vendor:publish --provider="Jenky\Transmit\TransmitServiceProvider"
Configuration
After publishing Transmit's assets, its primary configuration file will be located at config/transmit.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.
Client configuration
A client is simply a 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 options
Set guzzle request options within the channel. Please visit Request Options for more information.
'clients' => [ 'github' => [ 'options' => [ 'base_uri' => 'https://api.github.com/v3/', 'time_out' => 20, ], ], ]
Then uses it in your code:
use Illuminate\Support\Facades\Http; Http::client('github')->get('....');
Customizing the client Pending Request
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 pending request instance after it is created:
'default' => [ 'tap' => [ App\Http\Client\CustomizeRequest::class, ], ],
Once you have configured the tap
option on your client, you're ready to define the class that will customize your client factory instance. This class only needs a single method: __invoke
, which receives an Illuminate\Http\Client\PendingRequest
instance.
<?php namespace App\Http\Client; use Illuminate\Http\Client\PendingRequest; class CustomizeRequest { /** * Customize the given client pending request instance. * * @param \Illuminate\Http\Client\PendingRequest $request * @return void */ public function __invoke(PendingRequest $request) { $request->withToken('my_access_token'); } }
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 UseLogger
class that receives a channel name as an additional argument.
Additional parameters will be passed to the class after the $request
argument:
<?php namespace App\Http\Client; use GuzzleHttp\MessageFormatter; use GuzzleHttp\Middleware; use Illuminate\Http\Client\PendingRequest; use Illuminate\Log\LogManager; class UseLogger { /** * 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 client pending request instance. * * @param \Illuminate\Http\Client\PendingRequest $request * @param string|null $channel * @param string $level * @return void */ public function __invoke(PendingRequest $request, ?string $channel = null, string $level = 'debug') { $request->withMiddleware(Middleware::log( $this->logger->channel($channel), new MessageFormatter, $level )); } }
"Tap" class parameters may be specified in transmit
config by separating the class name and parameters with a :
. Multiple parameters should be delimited by commas:
'my_client' => [ 'tap' => [ App\Http\Client\UseLogger::class.':slack,info', ], ],
You can also use closure
if you don't want to use class base method:
'my_client' => [ 'tap' => [ function (PendingRequest $request) { $request->asForm(); }, ], ],
Caveats
Inspecting faking requests
All the assert*
methods should be called from HTTP client instance instead of the Http
facade if requests are made from specific client.
use Illuminate\Http\Client\Request; use Illuminate\Support\Facades\Http; Http::fake(); Http::client('my_client')->get('foo'); Http::client('my_client')->assertSent(function (Request $request) { // }); Http::client('my_client')->assertNotSent(function (Request $request) { // });
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
License
The MIT License (MIT). Please see License File for more information.