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

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.

jenky / transmit

Maintainers

Details