Updated documentation to reflect mutability changes

Author: weierophinney

CHANGELOG.md

@@ -66,6 +66,14 @@ All notable changes to this project will be documented in this file, in reverse
   Of course, you can still override the `validate` method if your logic is more
   complex.
 
+- A new method, `configure()`, was added, allowing full configuration of the
+  `ServiceManager` instance at once. Each of the various configuration methods —
+  `setAlias()`, `setInvokableClass()`, etc. — now proxy to this method.
+
+- A new method, `mapLazyService($name, $class = null)`, was added, to allow
+  mapping a lazy service, and as an analog to the other various service
+  definition methods.
+
 ### Deprecated
 
 - Nothing
@@ -114,20 +122,12 @@ changes, outlined in this section.
   `Config` and `ConfigInterface` still exist, however, but primarily for the
   purposes of codifying and aggregating configuration to use.
 
-- The ServiceManager is now immutable. Once configured, it cannot be altered.
-  You need to create a new service manager if you need to change the
-  configuration. This ensures safer and more aggressive caching. A new method,
-  `withConfig()`, allows you to create a new instance that merges the provided
-  configuration.
-
 - `ConfigInterface` has two important changes:
-  - `configureServiceManager()` now **must** return a service manager instance.
-    Since the ServiceManager is now immutable, and the various methods for
-    injecting services are gone, the expectation is that this method will pass
-    configuration to `ServiceManager::withConfig()` and return the new instance.
+  - `configureServiceManager()` now **must** return the updated service manager
+    instance.
   - A new method, `toArray()`, was added, to allow pulling the configuration in
     order to pass to a ServiceManager or plugin manager's constructor or
-    `withConfig()` method.
+    `configure()` method.
 
 - Interfaces for `FactoryInterface`, `DelegatorFactoryInterface` and
   `AbstractFactoryInterface` have changed. All are now directly invokable. This

doc/book/configuring-the-service-manager.md

@@ -484,14 +484,31 @@ This works because the `InvokableFactory` will automatically pass the options
 
 ## Altering a service manager's config
 
-The service manager is immutable. This means that once you have created a
-service manager instance, you cannot alter its configuration. This is done for
-performance reasons, as it allows us to more aggressively cache.
-
-However, you may need to alter its configuration at runtime in order to add new
-factories. To do that, you can use the `withConfig()` method. This method creates a
-*new* service manager instance, which merges its own configuration with the new
-configuration you provide to it:
+Assuming that you have not called `$container->setAllowOverride(false)`, you can,
+at any time, configure the service manager with new services using any of the
+following methods:
+
+- `configure()`, which accepts the same configuration array as the constructor.
+- `setAlias($alias, $target)`
+- `setInvokableClass($name, $class = null)`; if no `$class` is passed, the
+  assumption is that `$name` is the class name.
+- `setFactory($name, $factory)`, where `$factory` can be either a callable
+  factory or the name of a factory class to use.
+- `mapLazyService($name, $class = null)`, to map the service name `$name` to
+  `$class`; if the latter is not provided, `$name` is used for both sides of
+  the map.
+- `addAbstractFactory($factory)`, where `$factory` can be either a
+  `Zend\ServiceManager\Factory\AbstractFactoryInterface` instance or the name
+  of a class implementing the interface.
+- `addDelegator($name, $factory)`, where `$factory` can be either a callable
+  delegator factory, or the name of a delegator factory class to use.
+- `addInitializer($initializer)`, where `$initializer` can be either a callable
+  initializer, or the name of an initializer class to use.
+- `setService($name, $instance)`
+- `setShared($name, $shared)`, where `$shared` is a boolean flag indicating
+  whether or not the named service should be shared.
+
+As examples:
 
 ```php
 use Zend\ServiceManager\ServiceManager;
@@ -502,18 +519,47 @@ $serviceManager = new ServiceManager([
     ]
 ]);
 
-$newServiceManager = $serviceManager->withConfig([
+$serviceManager->configure([
     'factories' => [
         DateTime::class => InvokableFactory::class
     ]
 ]);
 
-var_dump($serviceManager->has(DateTime::class)); // prints false
 var_dump($newServiceManager->has(DateTime::class)); // prints true
-```
 
-As you can see from this example, the old service manager has been untouched,
-and therefor does not contain any factory set for the `DateTime` service.
+// Create an alias from 'Date' to 'DateTime'
+$serviceManager->setAlias('Date', DateTime::class);
+
+// Set a factory for the 'Time' service
+$serviceManager->setFactory('Time', function ($container) {
+    return $container->get(DateTime::class);
+});
+
+// Map a lazy service named 'localtime' to the class DateTime.
+$serviceManager->mapLazyService('localtime', DateTime::class);
+
+// Add an abstract factory
+$serviceManager->addAbstractFactory(new CustomAbstractFactory());
 
-> When creating a new service manager through the `withConfig` method, **no
-> services** created with the old service manager are cloned.
+// Add a delegator factory for the DateTime service
+$serviceManager->addDelegator(DateTime::class, function ($container, $name, $callback) {
+    $dateTime = $callback();
+    $dataTime->setTimezone(new DateTimezone('UTC'));
+    return $dateTime;
+});
+
+// Add an initializer
+// Note: don't do this. Use delegator factories instead.
+$serviceManager->addInitializer(function ($service, $instance) {
+    if (! $instance instanceof DateTime) {
+        return;
+    }
+    $instance->setTimezone(new DateTimezone('America/Chicago'));
+})
+
+// Explicitly map a service name to an instance.
+$serviceManager->setService('foo', new stdClass);
+
+// Mark the DateTime service as NOT being shared.
+$serviceManager->setShared(DateTime::class, false);
+```

doc/book/lazy-services.md

@@ -122,7 +122,7 @@ in the `lazy_services` key passed in the service manager configuration:
 [
     // map of service names and their relative class names - this
     // is required since the service manager cannot know the
-    // class name of defined services upfront
+    // class name of defined services up front
     'class_map' => [
         // 'foo' => 'MyApplication\Foo',
     ],
@@ -137,3 +137,10 @@ in the `lazy_services` key passed in the service manager configuration:
     '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);
+```

doc/book/migration.md

@@ -311,6 +311,16 @@ return [
 ];
 ```
 
+Additionally, assuming you have configured lazy services initially with the
+proxy namespace, target directory, etc., you can map lazy services using the new
+method `mapLazyService($name, $class)`:
+
+```php
+$container->mapLazyService('MyClass', 'MyClass');
+// or, more simply:
+$container->mapLazyService('MyClass');
+```
+
 ## ServiceLocatorInterface Changes
 
 The `ServiceLocatorInterface` now extends the
@@ -332,70 +342,32 @@ service, and to allow using the provided `$options` when creating the instance.
 `Zend\ServiceManager\ServiceManager` remains the primary interface with which
 developers will interact. It has the following changes in v3:
 
-- It is now immutable.
-  - It accepts all configuration at instantiation.
-  - It removes all methods that would alter state.
-  - It adds a new method, `withConfig()`, for generating a new instance that
-    merges the provided configuration with previous definitions.
+- It adds a new method, `configure()`, which allows configuring all instance
+  generation capabilities (aliases, factories, abstract factories, etc.) at
+  once.
 - Peering capabilities were removed.
 - Exceptions are *always* thrown when service instance creation fails or
   produces an error; you can no longer disable this.
-- Configuration no longer requires a `Zend\ServiceManager\Config` instance; that
-  class has been removed.
+- Configuration no longer requires a `Zend\ServiceManager\Config` instance.
+  `Config` can be used, but is no needed.
 - It adds a new method, `build()`, for creating discrete service instances.
 
 ### Methods Removed
 
 *The following methods are removed* in v3:
 
-- `setAllowOverride()`/`getAllowOverride()`; since instances are now immutable,
-  these no longer had any meaning.
 - `setShareByDefault()`/`shareByDefault()`; this can be passed during
-  instantiation or via `withConfig()`.
+  instantiation or via `configure()`.
 - `setThrowExceptionInCreate()`/`getThrowExceptionInCreate()`; exceptions are
   *always* thrown when errors are encountered during service instance creation.
 - `setRetrieveFromPeeringManagerFirst()`/`retrieveFromPeeringManagerFirst()`;
   peering is no longer supported.
-- `setInvokableClass()`; invokable classes are no longer supported separately,
-  regardless.
-- `setFactory()`; pass factories during instantiation or via `withConfig()`.
-- `addAbstractFactory()`; provide abstract factories during instantiation or via
-  `withConfig()`.
-- `addDelegator()`; provide delegator factories during instantiation or via
-  `withConfig()`.
-- `addInitializer()`; pass initializers during instantiation or via
-  `withConfig()`.
-- `setService()`; provide concrete service instances during instantiation or via
-  `withConfig()`.
-- `setShared()`/`isShared()`; provide per-service sharing status at
-  instantiation or via `withConfig()`.
 
 ### Constructor
 
 The constructor now accepts an array of service configuration, not a
 `Zend\ServiceManager\Config` instance.
 
-### Immutability
-
-The Service Manager is now immutable. This allows us to perform aggressive
-caching, and prevents the need to check for state changes when new services are
-added.
-
-*Typically, you should pass all service configuration at instantiation.*
-
-If you need to change a Service Manager instance — for instance, to add more
-factories, delegators, etc. — the class provides a new method, `withConfig()`.
-This method will merge the configuration you provide with that found in the
-Service Manager instance in order to return a *new instance*:
-
-```php
-$updated = $container->withConfig([
-    'factories' => [
-        'MyClass' => InvokableFactory::class,
-    ],
-]);
-```
-
 ### Use `build()` for discrete instances
 
 The new method `build()` acts as a factory method for configured services, and
@@ -758,10 +730,8 @@ The following classes and interfaces have changes:
 - `Zend\ServiceManager\Proxy\LazyServiceFactory` is now marked `final`, and
    implements `Zend\ServiceManager\Proxy\DelegatorFactoryInterface`. Its
    dependencies and capabilities remain the same.
-- `Zend\ServiceManager\ConfigInterface` now is expected to *return* a
-  `ServiceManager` instance. This is because instances cannot be configured
-  in-situ; implementers will now need to call `withConfig()` and return the
-  instance returned by that method.
+- `Zend\ServiceManager\ConfigInterface` now is expected to *return* the modified
+  `ServiceManager` instance.
 - `Zend\ServiceManager\Config` was updated to follow the changes to
-  `ConfigInterface` and `ServiceManager`, and now returns a new
+  `ConfigInterface` and `ServiceManager`, and now returns the updated
   `ServiceManager` instance from `configureServiceManager()`.