Normalize adapter configuration

[boesing]

Feature Request

Q	A
New Feature	yes
BC Break	yes (in 3.0)/no (in 2.x, just deprecating it)

Summary

Specify Adapter Configuration

There are multiple specifications of configurations in laminas-cache v2 to create an adapter with plugins and options.

These specifications are:

<?php

use Laminas\Cache\Storage\Adapter\Memory;
use Laminas\Cache\Storage\Plugin\IgnoreUserAbort;
use Laminas\Cache\StorageFactory;

StorageFactory::factory([
    'adapter' => 'memory',
    'options' => [],
    'plugins' => ['Serializer'],
]);

StorageFactory::factory([
    'adapter' => [
        'name' => Memory::class,
        'options' => [],
    ],
    'options' => [], // Yes! These are getting merged with those from `adapter.options` ...
    'plugins' => [
        IgnoreUserAbort::class => ['exitOnAbort' => true],
    ],
]);

StorageFactory::factory([
    'adapter' => Memory::class,
    'options' => [],
    'plugins' => [
        [
            'name' => IgnoreUserAbort::class,
            'options' => ['exitOnAbort' => true],
            'priority' => PHP_INT_MAX,
        ],
    ],
]);

In v3, we should limit the specification to one configuration which can be used with the upcoming StorageAdapterFactory.

use Laminas\Cache\Storage\Adapter\Memory;
use Laminas\Cache\Storage\Plugin\IgnoreUserAbort;

[
    'adapter' => Memory::class,
    'options' => [],
    'plugins' => [
        [
            'name' => IgnoreUserAbort::class,
            'options' => ['exitOnAbort' => true],
            'priority' => PHP_INT_MAX,
        ],
    ],
];

The psalm notation of this configuration would look like this:

/**
 * @psalm-type InternalOptionalPriorityConfigurationType = array{priority?:int}
 * @psalm-type InternalPluginArrayConfigurationType = array{name:string,options?:array<string,mixed>}
 * @psalm-type PluginArrayConfigurationWithPriorityType = InternalPluginArrayConfigurationType&InternalOptionalPriorityConfigurationType
 * @psalm-type StorageAdapterArrayConfigurationType = array{
 *     name: non-empty-string,
 *     options?: array<string,mixed>,
 *     plugins?: list<PluginArrayConfigurationWithPriorityType>
 * }
 */

To help users migrate their existing configurations, we might want to provide a laminas-cli command to migrate from the old structure to the new structure.

[boesing]

Closed with #104