docs & refactor of logging

changelog.md

@@ -6,8 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [3.8.0]
+
 ### Added
 - Updating the index alias is now done through a (queueable) job.
+- Nested aggregations in the results.
+- Option to enable a PSR-3 compliant logger.
+- Allow custom order by (as a syntax object).
 
 ## [3.7.0]
 

config/explorer.php

@@ -38,5 +38,10 @@
      */
     'prune_old_aliases' => true,
 
-    'logger' => env('EXPLORER_ELASTIC_LOGGER_ENABLED', false),
+    /**
+     * When set to true, sends all the logs (requests, responses, etc.) from the Elasticsearch PHP SDK
+     * to a PSR-3 logger. Disabled by default for performance.
+     */
+    'logging' => env('EXPLORER_ELASTIC_LOGGER_ENABLED', false),
+    'logger' => null,
 ];

docs/index.md

@@ -29,6 +29,7 @@ Also do not forget to follow the [installation instructions for Laravel Scout](h
 - [Sorting search results](sorting.md)
 - [Pagination and search result size](pagination.md)
 - [Debugging](debugging.md)
+- [Logging](logging.md)
 - [Testing](testing.md)
 - [Console commands](commands.md)
 - [Text analysis](text-analysis.md)

docs/logging.md

@@ -0,0 +1,17 @@
+# Logging
+
+When enabled the Elastic SDK will send all its logs (such as requests and responses) to a PSR-3 logger. 
+By default the logger is disabled for performance.
+To enable the logger set `EXPLORER_ELASTIC_LOGGER_ENABLED=true` in your environment variables and edit your `explorer.php` config to define a logger (see below for examples).
+
+See also the [SDK](https://github.com/elastic/elasticsearch-php/blob/main/docs/logger.asciidoc) docs.
+More information on loggers in Laravel can be found in [Laravel's docs](https://laravel.com/docs/logging).
+
+Examples:
+```php
+'logger' => new \Psr\Log\NullLogger(),
+```
+
+```php
+'logger' => \Illuminate\Support\Facades\Log::channel('daily'),
+```

src/ExplorerServiceProvider.php

@@ -50,10 +50,9 @@ public function boot(): void
 
         $this->app->when(ElasticClientFactory::class)
             ->needs(Client::class)
-            ->give(static fn () => ElasticClientBuilder::fromConfig(
-                config(),
-                logger()
-            )->build());
+            ->give(
+                static fn () => ElasticClientBuilder::fromConfig(config(), logger())->build()
+            );
 
         $this->app->when(ElasticDocumentAdapter::class)
             ->needs(Client::class)

src/Infrastructure/Elastic/ElasticClientBuilder.php

@@ -4,16 +4,14 @@
 
 namespace JeroenG\Explorer\Infrastructure\Elastic;
 
-use Elasticsearch\Client;
 use Elasticsearch\ClientBuilder;
 use Illuminate\Contracts\Config\Repository;
-use Psr\Log\LoggerInterface;
 
 final class ElasticClientBuilder
 {
     private const HOST_KEYS = ['host', 'port', 'scheme'];
 
-    public static function fromConfig(Repository $config, LoggerInterface $logger): ClientBuilder
+    public static function fromConfig(Repository $config): ClientBuilder
     {
         $builder = ClientBuilder::create();
 
@@ -66,8 +64,8 @@ public static function fromConfig(Repository $config, LoggerInterface $logger):
             $builder->setSSLCert($path, $password);
         }
 
-        if($config->get('explorer.logger', false)) {
-            $builder->setLogger($logger);
+        if($config->get('explorer.logging', false) && $config->has('explorer.logger')) {
+            $builder->setLogger($config->get('explorer.logger'));
         }
 
         return $builder;

tests/Unit/ElasticClientBuilderTest.php

@@ -8,8 +8,8 @@
 use Illuminate\Container\Container;
 use JeroenG\Explorer\Infrastructure\Elastic\ElasticClientBuilder;
 use JeroenG\Explorer\Tests\Support\ConfigRepository;
-use JeroenG\Explorer\Tests\Support\Logger;
 use Mockery\Adapter\Phpunit\MockeryTestCase;
+use Psr\Log\NullLogger;
 
 final class ElasticClientBuilderTest extends MockeryTestCase
 {
@@ -21,16 +21,15 @@ final class ElasticClientBuilderTest extends MockeryTestCase
     public function test_it_creates_client_with_config(array $config, ClientBuilder $expectedBuilder): void
     {
         $configRepository = new ConfigRepository([ 'explorer' => $config ]);
-        $logger = new Logger();
 
         Container::getInstance()->instance('config', $configRepository);
 
-        $resultBuilder  = ElasticClientBuilder::fromConfig($configRepository, $logger);
+        $resultBuilder  = ElasticClientBuilder::fromConfig($configRepository);
 
         self::assertEquals($expectedBuilder, $resultBuilder);
     }
 
-    public function provideClientConfigs()
+    public function provideClientConfigs(): ?\Generator
     {
         yield 'simple host' => [
             [
@@ -152,5 +151,35 @@ public function provideClientConfigs()
                 ->setSSLCert('path/to/cert.pem')
                 ->setSSLKey('path/to/key.pem'),
         ];
+
+        yield 'with logging' => [
+            [
+                'logging' => true,
+                'logger' => new NullLogger(),
+                'connection' => self::CONNECTION,
+            ],
+            ClientBuilder::create()
+                ->setHosts([self::CONNECTION])
+                ->setLogger(new NullLogger()),
+        ];
+
+        yield 'without logging' => [
+            [
+                'logging' => false,
+                'logger' => new NullLogger(),
+                'connection' => self::CONNECTION,
+            ],
+            ClientBuilder::create()
+                ->setHosts([self::CONNECTION]),
+        ];
+
+        yield 'without logger' => [
+            [
+                'logger' => new NullLogger(),
+                'connection' => self::CONNECTION,
+            ],
+            ClientBuilder::create()
+                ->setHosts([self::CONNECTION]),
+        ];
     }
 }