feature: allow adapter as configuration key when using `StoragePlug…

…inFactoryInterface`

In v2.12.0, we provided a normalized array structure along with a configuration check command. When a project is being migrated from latest v2 version to v3, it will still break due to an incompatible configuration. This was changed in v3 and was not backported to v2 before releasing v3.

With this patch, the `name` configuration key will be deprecated in favor of the `adapter` configuration key to ensure better backwards compatibility.

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>

src/Service/StoragePluginFactory.php

@@ -24,7 +24,8 @@ public function __construct(PluginManagerInterface $plugins)
 
     public function createFromArrayConfiguration(array $configuration): PluginInterface
     {
-        $name    = $configuration['name'];
+        $name = $configuration['adapter'] ?? $configuration['name'] ?? null;
+        Assert::stringNotEmpty($name, 'Configuration must contain a "adapter" key.');
         $options = $configuration['options'] ?? [];
 
         return $this->create($name, $options);
@@ -41,8 +42,15 @@ public function assertValidConfigurationStructure(array $configuration): void
     {
         try {
             Assert::isNonEmptyMap($configuration, 'Configuration must be a non-empty array.');
-            Assert::keyExists($configuration, 'name', 'Configuration must contain a "name" key.');
-            Assert::stringNotEmpty($configuration['name'], 'Plugin "name" has to be a non-empty string.');
+            if (! isset($configuration['name']) && ! isset($configuration['adapter'])) {
+                throw new PhpInvalidArgumentException('Configuration must contain a "adapter" key.');
+            }
+
+            Assert::stringNotEmpty(
+                $configuration['adapter'] ?? $configuration['name'],
+                'Plugin "adapter" has to be a non-empty string.'
+            );
+
             Assert::nullOrIsMap(
                 $configuration['options'] ?? null,
                 'Plugin "options" must be an array with string keys.'

src/Service/StoragePluginFactoryInterface.php

@@ -8,7 +8,7 @@
 use Laminas\Cache\Storage\Plugin\PluginInterface;
 
 /**
- * @psalm-type PluginArrayConfigurationType = array{name:non-empty-string,options?:array<string,mixed>}
+ * @psalm-type PluginArrayConfigurationType = array{name:non-empty-string,options?:array<string,mixed>}|array{adapter:non-empty-string,options?:array<string,mixed>}
  */
 interface StoragePluginFactoryInterface
 {

test/Service/StoragePluginFactoryTest.php

@@ -37,18 +37,18 @@ public function invalidConfigurations(): Generator
             'Configuration must be a non-empty array',
         ];
 
-        yield 'missing name' => [
+        yield 'missing adapter' => [
             ['options' => []],
-            'Configuration must contain a "name" key',
+            'Configuration must contain a "adapter" key',
         ];
 
-        yield 'empty name' => [
-            ['name' => ''],
-            'Plugin "name" has to be a non-empty string',
+        yield 'empty adapter name' => [
+            ['adapter' => ''],
+            'Plugin "adapter" has to be a non-empty string',
         ];
 
         yield 'invalid options' => [
-            ['name' => 'foo', 'options' => 'bar'],
+            ['adapter' => 'foo', 'options' => 'bar'],
             'Plugin "options" must be an array with string keys',
         ];
     }
@@ -57,6 +57,20 @@ public function testWillCreatePluginFromArrayConfiguration(): void
     {
         $plugin = $this->createMock(PluginInterface::class);
 
+        $this->plugins
+            ->expects(self::once())
+            ->method('build')
+            ->with('foo')
+            ->willReturn($plugin);
+
+        $createdPlugin = $this->factory->createFromArrayConfiguration(['adapter' => 'foo']);
+        self::assertSame($plugin, $createdPlugin);
+    }
+
+    public function testWillCreatePluginFromDeprecatedArrayConfiguration(): void
+    {
+        $plugin = $this->createMock(PluginInterface::class);
+
         $this->plugins
             ->expects(self::once())
             ->method('build')
@@ -78,7 +92,7 @@ public function testWillCreatePluginFromArrayConfigurationWithOptions(): void
             ->willReturn($plugin);
 
         $createdPlugin = $this->factory->createFromArrayConfiguration(
-            ['name' => 'foo', 'options' => ['bar' => 'baz']]
+            ['adapter' => 'foo', 'options' => ['bar' => 'baz']]
         );
 
         self::assertSame($plugin, $createdPlugin);
@@ -131,7 +145,7 @@ public function testWillAssertProperConfiguration(): void
     {
         $this->expectNotToPerformAssertions();
         $this->factory->assertValidConfigurationStructure([
-            'name'    => 'foo',
+            'adapter' => 'foo',
             'options' => ['bar' => 'baz'],
         ]);
     }