Merge pull request #2 from Astrotomic/dev-v2

v2.0.0

.gitignore

@@ -1,4 +1,4 @@
 /vendor/
 /composer.lock
 /phpunit.xml
-/build/
+/coverage/

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `laravel-guzzle` will be documented in this file
 
+## 2.0.0 - 2020-02-24
+
+- [upgrade guide](https://github.com/Astrotomic/laravel-guzzle/pull/2#issue-378649298)
+- added `default_client` and `clients` config keys
+- added `\Astrotomic\LaravelGuzzle\Factory` as new core of the package
+- changed `\Astrotomic\LaravelGuzzle\Facades\Guzzle` to pipe calls to the new factory
+- dropped `guzzle()` helper function 
+- renamed service-provider from `LaravelGuzzleServiceProvider` to `GuzzleServiceProvider`
+
 ## 1.0.1 - 2020-02-17
 
 - upgrade guzzle to at least v6.3

README.md

@@ -29,38 +29,67 @@ php artisan vendor:publish --provider="Astrotomic\LaravelGuzzle\LaravelGuzzleSer
 
 ## Usage
 
-### Helper
-
-You can use the helper function to create a new instance of `GuzzleHttp\Client`. The helper function has two optional arguments. The `base_uri` and a `config` array. Both are merged with the default config defined in the package config file.
+The core of this package is the `\Astrotomic\LaravelGuzzle\Factory` which can handle multiple guzzle clients.
+There's also a facade that forwards calls to the factory.
 
 ```php
-$guzzle = guzzle('https://example.com', [
-    RequestOptions::CONNECT_TIMEOUT => 3,
-]);
+use Astrotomic\LaravelGuzzle\Facades\Guzzle;
+use Psr\Http\Message\ResponseInterface;
+
+/** @var ResponseInterface $response */
+$response = Guzzle::client('jsonplaceholder')->get('posts/1');
+$response->getStatusCode(); // 200
 ```
 
-### Injection
+### Default Client
+
+By default the `default_client` config refers to a `default` client.
+The `clients` config key holds all client specific configs.
+For all possible request options please refer to the [official guzzle docs](http://docs.guzzlephp.org/en/stable/request-options.html).
+
+### new Clients
 
-Because this package binds the guzzle client with the container you can use injection. The only downside is that you aren't able to set a `base_uri` this way.
+There are multiple ways to register a new client - the easiest would be to simply add a new config to the `clients` config key.
+This will also be the most common for users using the package in a Laravel app.
+
+#### Register config
+
+If you want to configure your clients from within a service provider you can use the `\Astrotomic\LaravelGuzzle\Factory::register()` method.
+The registered config will be merged with an optional app config.
+This will also come in handy for package developers who want to allow the fin al user to customize the guzzle config.
 
 ```php
-class MyClass 
+use Astrotomic\LaravelGuzzle\Facades\Guzzle;
+use Illuminate\Support\ServiceProvider;
+use GuzzleHttp\RequestOptions;
+
+class HttpServiceProvider extends ServiceProvider
 {
-    public function __construct(\GuzzleHttp\ClientInterface $guzzle)
+    public function boot(): void
     {
-        $this->guzzle = $guzzle;
+        Guzzle::register('jsonplaceholder', [
+            'base_uri' => 'https://jsonplaceholder.typicode.com',
+            RequestOptions::TIMEOUT => 3,
+        ]);
     }
 }
 ```
 
-### Make
+#### Register Creator
 
-For sure you can also make a client via any app container.
+If you have the need to create a real `GuzzleHttp\Client` instance yourself you can do so and assign it to an identifier.
+This way you can also use a custom client class - the only requirement is that it extends the basic `GuzzleHttp\Client` class.
 
 ```php
-$guzzle = app(\GuzzleHttp\ClientInterface::class, [
-    'base_uri' => 'https://example.com',
-]);
+use Astrotomic\LaravelGuzzle\Facades\Guzzle;
+use GuzzleHttp\Client;
+use Illuminate\Contracts\Container\Container;
+
+Guzzle::extend('astrotomic', static function (Container $app, ?array $config): Client {
+    return new Client(array_merge([
+        'base_uri' => 'https://astrotomic.info',
+    ], $config));
+});
 ```
 
 ### Testing

composer.json

@@ -3,7 +3,11 @@
     "description": "Laravel wrapper for guzzlehttp/guzzle",
     "keywords": [
         "astrotomic",
-        "laravel-guzzle"
+        "laravel-guzzle",
+        "guzzle",
+        "guzzlehttp",
+        "http",
+        "http-client"
     ],
     "homepage": "https://github.com/astrotomic/laravel-guzzle",
     "license": "MIT",
@@ -28,10 +32,7 @@
     "autoload": {
         "psr-4": {
             "Astrotomic\\LaravelGuzzle\\": "src"
-        },
-        "files": [
-            "src/helpers.php"
-        ]
+        }
     },
     "autoload-dev": {
         "psr-4": {
@@ -49,7 +50,7 @@
     "extra": {
         "laravel": {
             "providers": [
-                "Astrotomic\\LaravelGuzzle\\LaravelGuzzleServiceProvider"
+                "Astrotomic\\LaravelGuzzle\\GuzzleServiceProvider"
             ]
         }
     }

config/config.php

@@ -3,10 +3,16 @@
 use GuzzleHttp\RequestOptions;
 
 return [
+    'default_client' => 'default',
+
     'default_config' => [
         RequestOptions::TIMEOUT => 5,
         RequestOptions::CONNECT_TIMEOUT => 1,
         RequestOptions::HTTP_ERRORS => true,
         RequestOptions::ALLOW_REDIRECTS => true,
     ],
+
+    'clients' => [
+        'default' => [],
+    ],
 ];

src/Facades/Guzzle.php

@@ -2,6 +2,8 @@
 
 namespace Astrotomic\LaravelGuzzle\Facades;
 
+use Astrotomic\LaravelGuzzle\Factory as GuzzleFactory;
+use Closure;
 use GuzzleHttp\Client as GuzzleClient;
 use GuzzleHttp\ClientInterface as GuzzleClientContract;
 use GuzzleHttp\Promise\PromiseInterface;
@@ -11,6 +13,13 @@
 use Psr\Http\Message\UriInterface;
 
 /**
+ * @see GuzzleFactory
+ * @method static GuzzleClient make($baseUri = null, array $config = [])
+ * @method static GuzzleClient client(?string $driver = null)
+ * @method static GuzzleFactory extend(string $driver, Closure $callback)
+ * @method static GuzzleFactory register(string $identifier, array $config)
+ * @method static array getDrivers()
+ *
  * @see GuzzleClientContract
  * @method static ResponseInterface send(RequestInterface $request, array $options = [])
  * @method static PromiseInterface sendAsync(RequestInterface $request, array $options = [])
@@ -35,6 +44,6 @@ class Guzzle extends Facade
 {
     protected static function getFacadeAccessor(): string
     {
-        return GuzzleClientContract::class;
+        return GuzzleFactory::class;
     }
 }

src/Factory.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Astrotomic\LaravelGuzzle;
+
+use GuzzleHttp\Client as GuzzleClient;
+use Illuminate\Support\Manager;
+use InvalidArgumentException;
+use Psr\Http\Message\UriInterface;
+
+class Factory extends Manager
+{
+    /**
+     * The registered custom client configs.
+     *
+     * @var array[]
+     */
+    protected $registeredConfigs = [];
+
+    /**
+     * @param string|UriInterface|null $baseUri
+     * @param array $config
+     *
+     * @return GuzzleClient
+     */
+    public function make($baseUri = null, array $config = []): GuzzleClient
+    {
+        if ($baseUri !== null) {
+            $config['base_uri'] = $baseUri;
+        }
+
+        return $this->createClient($config);
+    }
+
+    public function client(?string $identifier = null): GuzzleClient
+    {
+        return $this->driver($identifier);
+    }
+
+    public function driver($driver = null): GuzzleClient
+    {
+        return parent::driver($driver);
+    }
+
+    public function getDefaultDriver(): string
+    {
+        return $this->config->get('guzzle.default_client');
+    }
+
+    public function register(string $identifier, array $config): self
+    {
+        $this->registeredConfigs[$identifier] = $config;
+
+        return $this;
+    }
+
+    protected function createDriver($driver): GuzzleClient
+    {
+        if (isset($this->customCreators[$driver])) {
+            return $this->callCustomCreator($driver);
+        } elseif (isset($this->registeredConfigs[$driver])) {
+            return $this->createClient(array_merge(
+                $this->registeredConfigs[$driver],
+                $this->config->get('guzzle.clients.'.$driver, [])
+            ));
+        } elseif ($this->config->has('guzzle.clients.'.$driver)) {
+            return $this->createClient(
+                $this->config->get('guzzle.clients.'.$driver)
+            );
+        }
+
+        throw new InvalidArgumentException("Client [$driver] not supported.");
+    }
+
+    protected function callCustomCreator($driver): GuzzleClient
+    {
+        return $this->customCreators[$driver](
+            $this->container,
+            $this->prepareConfig($this->config->get('guzzle.clients.'.$driver, []))
+        );
+    }
+
+    protected function prepareConfig(array $config): array
+    {
+        return array_merge(
+            $this->config->get('guzzle.default_config', []),
+            $config
+        );
+    }
+
+    protected function createClient(array $config): GuzzleClient
+    {
+        return new GuzzleClient($this->prepareConfig($config));
+    }
+}

src/LaravelGuzzleServiceProvider.php → src/GuzzleServiceProvider.php

@@ -7,7 +7,7 @@
 use Illuminate\Contracts\Container\Container;
 use Illuminate\Support\ServiceProvider;
 
-class LaravelGuzzleServiceProvider extends ServiceProvider
+class GuzzleServiceProvider extends ServiceProvider
 {
     public function boot(): void
     {
@@ -22,16 +22,15 @@ public function register(): void
     {
         $this->mergeConfigFrom(__DIR__.'/../config/config.php', 'guzzle');
 
+        $this->app->singleton(Factory::class);
+
         $this->app->bind(
-            GuzzleClientContract::class,
-            static function (Container $app, array $config): GuzzleClientContract {
-                return new GuzzleClient(array_merge(
-                    $app->make('config')->get('guzzle.default_config', []),
-                    $config
-                ));
+            GuzzleClient::class,
+            static function (Container $app): GuzzleClient {
+                return $app->make(Factory::class)->client();
             }
         );
 
-        $this->app->alias(GuzzleClientContract::class, GuzzleClient::class);
+        $this->app->alias(GuzzleClient::class, GuzzleClientContract::class);
     }
 }