Fixes documentation to support different versions

This commit removes numerous outdated and unnecessary documentation files in favor of v3 and v4 specific documentation. It also updates minor details in different documents for v4, removes old version hints and adds missing files for the documentation of version 3 again.

Reference: https://github.com/laminas/laminas-servicemanager/actions/runs/8137900822
Signed-off-by: Frank Brückner <[email protected]>

docs/book/index.md

@@ -0,0 +1,3 @@
+# This Is Only a Placeholder
+
+The content of this page is automatically generated.

docs/book/v3/cookbook/factories-vs-abstract-factories.md

@@ -49,14 +49,14 @@ The service manager is optimized to locate *factories*, as it can do an
 immediate hash table lookup; abstract factories involve:
 
 - Looping through each abstract factory
-  - invoking its method for service location
-  - if the service is located, using the factory
+    - invoking its method for service location
+    - if the service is located, using the factory
 
 This means, internally:
 
 - a hash table lookup (for the abstract factory)
 - invocation of 1:N methods for discovery
-  - which may contain additional lookups and/or retrievals in the container
+    - which may contain additional lookups and/or retrievals in the container
 - invocation of a factory method (assuming successful lookup)
 
 As such, having an explicit map can aid performance dramatically.

docs/book/v3/lazy-services.md

@@ -0,0 +1,146 @@
+# Lazy Services
+
+`Laminas\ServiceManager` can use [delegator factories](delegators.md) to generate
+"lazy" references to your services.
+
+Lazy services are [proxies](http://en.wikipedia.org/wiki/Proxy_pattern) that
+get lazily instantiated, and keep a reference to the real instance of
+the proxied service.
+
+## Use cases
+
+You may want to lazily initialize a service when it is instantiated very often,
+but not always used.
+
+A typical example is a database connection: it is a dependency to many other
+elements in your application, but that doesn't mean that every request will
+execute queries through it.
+
+Additionally, instantiating a connection to the database may require some time
+and eat up resources.
+
+Proxying the database connection would allow you to delay that overhead until the
+object is really needed.
+
+## Setup
+
+`Laminas\ServiceManager\Proxy\LazyServiceFactory` is a [delegator factory](delegators.md)
+capable of generating lazy loading proxies for your services.
+
+The lazy service facilities depend on [ProxyManager](https://github.com/FriendsOfPHP/proxy-manager-lts);
+you will need to install that package before using the feature:
+
+```php
+$ composer require friendsofphp/proxy-manager-lts
+```
+
+## Practical example
+
+To demonstrate how a lazy service works, you may use the following `Buzzer`
+example class, which is designed to be slow at instantiation time for
+demonstration purposes:
+
+```php
+namespace MyApp;
+
+class Buzzer
+{
+    public function __construct()
+    {
+        // deliberately halting the application for 5 seconds
+        sleep(5);
+    }
+
+    public function buzz()
+    {
+        return 'Buzz!';
+    }
+}
+```
+
+You can then proceed and configure the service manager to generate proxies
+instead of real services:
+
+```php
+use MyApp\Buzzer;
+use Laminas\ServiceManager\Factory\InvokableFactory;
+use Laminas\ServiceManager\Proxy\LazyServiceFactory;
+use Laminas\ServiceManager\ServiceManager;
+
+$serviceManager = new \Laminas\ServiceManager\ServiceManager([
+    'factories' => [
+        Buzzer::class             => InvokableFactory::class,
+    ],
+    'lazy_services' => [
+         // Mapping services to their class names is required
+         // since the ServiceManager is not a declarative DIC.
+         'class_map' => [
+             Buzzer::class => Buzzer::class,
+         ],
+    ],
+    'delegators' => [
+        Buzzer::class => [
+            LazyServiceFactory::class,
+        ],
+    ],
+]);
+```
+
+This configuration tells the service manager to add the add
+`LazyServiceFactory` as a delegator for `Buzzer`.
+
+You can now retrieve the buzzer:
+
+```php
+use MyApp\Buzzer;
+
+$buzzer = $serviceManager->get(Buzzer::class);
+echo $buzzer->buzz();
+```
+
+To verify that the proxying occurred correctly, you can run the following code,
+which should delay the 5 seconds wait time hardcoded in `Buzzer::__construct`
+until `Buzzer::buzz` is invoked:
+
+```php
+use MyApp\Buzzer;
+
+for ($i = 0; $i < 100; $i += 1) {
+    $buzzer = $serviceManager->get(Buzzer::class);
+    echo "created buzzer $i\n";
+}
+
+echo $buzzer->buzz();
+```
+
+## Configuration
+
+This is the config structure expected by `Laminas\ServiceManager\Proxy\LazyServiceFactory`,
+in the `lazy_services` key passed in the service manager configuration:
+
+```php
+[
+    // map of service names and their relative class names - this
+    // is required since the service manager cannot know the
+    // class name of defined services up front
+    'class_map' => [
+        // 'foo' => 'MyApplication\Foo',
+    ],
+
+    // directory where proxy classes will be written - default to system_get_tmp_dir()
+    'proxies_target_dir' => null,
+
+    // namespace of the generated proxies, default to "ProxyManagerGeneratedProxy"
+    'proxies_namespace' => null,
+
+    // whether the generated proxy classes should be written to disk or generated on-the-fly
+    'write_proxy_files' => false,
+];
+```
+
+After you have an instance, you can map lazy service/class pairs using
+`mapLazyService()`:
+
+```php
+$container->mapLazyService('foo', \MyApplication\Foo::class);
+```

docs/book/v3/migration.md

@@ -952,9 +952,9 @@ In addition, review the following changes.
 #### Constructor
 
 - The constructor now accepts the following arguments, in the following order:
-  - The parent container instance; this is usually the application-level
+    - The parent container instance; this is usually the application-level
     `ServiceManager` instance.
-  - Optionally, an array of configuration for the plugin manager instance; this
+    - Optionally, an array of configuration for the plugin manager instance; this
     should have the same format as for a `ServiceManager` instance.
 - `validatePlugin()` was renamed to `validate()` (now defined in
   `PluginManagerInterface`). The `AbstractPluginManager` provides

docs/book/v3/plugin-managers.md

@@ -0,0 +1,92 @@
+# Plugin managers
+
+Plugin managers are *specialized* service managers, typically used to create
+homogeneous objects of a specific type.
+
+Because a plugin manager extends a service manager, it works the same and can
+be configured similarly. It provides a separation of concerns (it will be used
+in specific contexts), and provides additional instance validation.
+
+Laminas components extensively use plugin managers to create services
+that share common functionalities. For instance, all validator services are
+specified inside a specialized `ValidatorPluginManager`.
+
+## Creating a plugin manager
+
+To create a plugin manager, you first need to create a new class that extends
+`Laminas\ServiceManager\AbstractPluginManager`:
+
+```php
+class ValidatorPluginManager extends AbstractPluginManager
+{
+    protected $instanceOf = ValidatorInterface::class;
+}
+```
+
+The `$instanceOf` variable specifies a class/interface type that all instances
+retrieved from the plugin manager must fulfill. If an instance created by the
+plugin manager does not match, a `Laminas\ServiceManager\Exception\InvalidServiceException`
+exception will be thrown.
+
+Most of the time, this shortcut is enough. However if you have more complex
+validation rules, you can override the `validate()` method:
+
+```php
+class ValidatorPluginManager extends AbstractPluginManager
+{
+    public function validate($instance)
+    {
+        if ($instance instanceof Foo || $instance instanceof Bar) {
+            return;
+        }
+
+        throw new InvalidServiceException('This is not a valid service!');
+    }
+}
+```
+
+## Configuring a plugin manager
+
+A plugin manager requires that you pass a parent service manager (typically,
+the application's service manager) as well as service configuration. Service
+configuration follows the exact same pattern as for a normal service manager;
+refer to the [configuring the service manager](configuring-the-service-manager.md) section for details.
+
+Because a plugin manager is often a service itself, we recommend you to
+register the plugin manager as part of the general service manager, as shown
+below:
+
+```php
+$serviceManager = new ServiceManager([
+    'factories' => [
+        ValidatorPluginManager::class => function(ContainerInterface $container, $requestedName) {
+            return new ValidatorPluginManager($container, [
+                'factories' => [
+                    StringLengthValidator::class => InvokableFactory::class,
+                ],
+            ]);
+        },
+    ],
+]);
+
+// Get the plugin manager:
+
+$pluginManager = $serviceManager->get(ValidatorPluginManager::class);
+
+// Use the plugin manager
+
+$validator = $pluginManager->get(StringLengthValidator::class);
+```
+
+> Unlike the version 2 implementation, when inside the context of the factory
+> of a service created by a plugin manager, the passed container **will not
+> be** the plugin manager, but the parent service manager instead. If you need
+> access to other plugins of the same type, you will need to fetch the plugin
+> manager from the container:
+>
+> ```php
+> function ($container, $name, array $options = []) {
+>     $validators = $container->get(ValidatorPluginManager::class);
+>     // ...
+> }
+> ```