Merge pull request #214 from Jeroen-G/logging

Logging

Makefile

@@ -17,10 +17,11 @@ reset: intro do-clean install
 # Tests
 tests: intro do-test-phpunit do-test-report
 mutations: intro do-test-infection do-test-report
+phpstan: intro do-phpstan
 
 # Development
 pre-commit: intro do-lint-staged-files do-commit-intro
-codestyle: intro do-cs-ecs
+codestyle: intro do-cs-ecs do-phpstan
 codestyle-fix: intro do-cs-ecs-fix
 
 # ===========================
@@ -35,6 +36,7 @@ help:
 	@echo "\nTests"
 	@echo "    make tests                     Run phpunit tests."
 	@echo "    make mutations                 Run the infection mutation tests."
+	@echo "    make phpstan	                  Run PHPStan."
 	@echo "\nDevelopment"
 	@echo "    make codestyle                 Check if the codestyle is OK."
 	@echo "    make codestyle-fix             Check and fix your messy codestyle."
@@ -84,3 +86,7 @@ do-test-report:
 	@echo "report/index.html"
 	@echo "\n=== Click the link below to see the mutation coverage report ===\n"
 	@echo "report/infection.html"
+
+do-phpstan:
+	@echo "\n=== Running PHPStan ===\n"
+	 vendor/bin/phpstan analyse

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]
 

composer.json

@@ -16,7 +16,8 @@
         "elasticsearch/elasticsearch": "^7.16",
         "illuminate/support": "^9.0||^10.0",
         "laravel/scout": "^9.0||^10.0",
-        "webmozart/assert": "^1.10"
+        "webmozart/assert": "^1.10",
+        "psr/log": "^1|^2|^3"
     },
     "require-dev": {
         "phpunit/phpunit": "~9.0",

config/explorer.php

@@ -37,4 +37,11 @@
      * A model is only using index aliases if it implements the Aliased interface.
      */
     'prune_old_aliases' => true,
+
+    /**
+     * 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/Infrastructure/Elastic/ElasticClientBuilder.php

@@ -4,7 +4,6 @@
 
 namespace JeroenG\Explorer\Infrastructure\Elastic;
 
-use Elasticsearch\Client;
 use Elasticsearch\ClientBuilder;
 use Illuminate\Contracts\Config\Repository;
 
@@ -65,6 +64,10 @@ public static function fromConfig(Repository $config): ClientBuilder
             $builder->setSSLCert($path, $password);
         }
 
+        if($config->get('explorer.logging', false) && $config->has('explorer.logger')) {
+            $builder->setLogger($config->get('explorer.logger'));
+        }
+
         return $builder;
     }
 

tests/Unit/ElasticClientBuilderTest.php

@@ -9,6 +9,7 @@
 use JeroenG\Explorer\Infrastructure\Elastic\ElasticClientBuilder;
 use JeroenG\Explorer\Tests\Support\ConfigRepository;
 use Mockery\Adapter\Phpunit\MockeryTestCase;
+use Psr\Log\NullLogger;
 
 final class ElasticClientBuilderTest extends MockeryTestCase
 {
@@ -20,14 +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 ]);
+
         Container::getInstance()->instance('config', $configRepository);
 
         $resultBuilder  = ElasticClientBuilder::fromConfig($configRepository);
 
         self::assertEquals($expectedBuilder, $resultBuilder);
     }
 
-    public function provideClientConfigs()
+    public function provideClientConfigs(): ?\Generator
     {
         yield 'simple host' => [
             [
@@ -149,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]),
+        ];
     }
 }