|
2 | 2 |
|
3 | 3 | All notable changes to this project will be documented in this file, in reverse chronological order by release. |
4 | 4 |
|
| 5 | +## v3.0.0 - TBD |
| 6 | + |
| 7 | +### Added |
| 8 | + |
| 9 | +- You can now map multiple key names to the same factory. It was previously |
| 10 | + possible in ZF2 but it was not enforced by the `FactoryInterface` interface. |
| 11 | + Now the interface receives the `$requestedName` as the *second* parameter |
| 12 | + (previously, it was the third). |
| 13 | + |
| 14 | + Example: |
| 15 | + |
| 16 | + ```php |
| 17 | + $sm = new \Zend\ServiceManager\ServiceManager([ |
| 18 | + 'factories' => [ |
| 19 | + MyClassA::class => MyFactory::class, |
| 20 | + MyClassB::class => MyFactory::class, |
| 21 | + 'MyClassC' => 'MyFactory' // This is equivalent as using ::class |
| 22 | + ], |
| 23 | + ]); |
| 24 | + |
| 25 | + $sm->get(MyClassA::class); // MyFactory will receive MyClassA::class as second parameter |
| 26 | + ``` |
| 27 | + |
| 28 | +- Writing a plugin manager has been simplified. If you have simple needs, you no |
| 29 | + longer need to implement the complete `validate` method. |
| 30 | + |
| 31 | + In versions 2.x, if your plugin manager only allows creating instances that |
| 32 | + implement `Zend\Validator\ValidatorInterface`, you needed to write the |
| 33 | + following code: |
| 34 | + |
| 35 | + ```php |
| 36 | + class MyPluginManager extends AbstractPluginManager |
| 37 | + { |
| 38 | + public function validate($instance) |
| 39 | + { |
| 40 | + if ($instance instanceof \Zend\Validator\ValidatorInterface) { |
| 41 | + return; |
| 42 | + } |
| 43 | + |
| 44 | + throw new InvalidServiceException(sprintf( |
| 45 | + 'Plugin manager "%s" expected an instance of type "%s", but "%s" was received', |
| 46 | + __CLASS__, |
| 47 | + \Zend\Validator\ValidatorInterface::class, |
| 48 | + is_object($instance) ? get_class($instance) : gettype($instance) |
| 49 | + )); |
| 50 | + } |
| 51 | + } |
| 52 | + ``` |
| 53 | + |
| 54 | + In version 3, this becomes: |
| 55 | + |
| 56 | + ```php |
| 57 | + use Zend\ServiceManager\AbstractPluginManager; |
| 58 | + use Zend\Validator\ValidatorInterface; |
| 59 | + |
| 60 | + class MyPluginManager extends AbstractPluginManager |
| 61 | + { |
| 62 | + protected $instanceOf = ValidatorInterface::class; |
| 63 | + } |
| 64 | + ``` |
| 65 | + |
| 66 | + Of course, you can still override the `validate` method if your logic is more |
| 67 | + complex. |
| 68 | + |
| 69 | + To aid migration, `validate()` will check for a `validatePlugin()` method (which |
| 70 | + was required in v2), and proxy to it if found, after emitting an |
| 71 | + `E_USER_DEPRECATED` notice prompting you to rename the method. |
| 72 | + |
| 73 | +- A new method, `configure()`, was added, allowing full configuration of the |
| 74 | + `ServiceManager` instance at once. Each of the various configuration methods — |
| 75 | + `setAlias()`, `setInvokableClass()`, etc. — now proxy to this method. |
| 76 | + |
| 77 | +- A new method, `mapLazyService($name, $class = null)`, was added, to allow |
| 78 | + mapping a lazy service, and as an analog to the other various service |
| 79 | + definition methods. |
| 80 | + |
| 81 | +### Deprecated |
| 82 | + |
| 83 | +- Nothing |
| 84 | + |
| 85 | +### Removed |
| 86 | + |
| 87 | +- Peering has been removed. It was a complex and rarely used feature that was |
| 88 | + misunderstood most of the time. |
| 89 | + |
| 90 | +- Integration with `Zend\Di` has been removed. It may be re-integrated later. |
| 91 | + |
| 92 | +- `MutableCreationOptionsInterface` has been removed, as options can now be |
| 93 | + passed directly through factories. |
| 94 | + |
| 95 | +- `ServiceLocatorAwareInterface` and its associated trait has been removed. It |
| 96 | + was an anti-pattern, and you are encouraged to inject your dependencies in |
| 97 | + factories instead of injecting the whole service locator. |
| 98 | + |
| 99 | +### Changed/Fixed |
| 100 | + |
| 101 | +v3 of the ServiceManager component is a completely rewritten, more efficient |
| 102 | +implementation of the service locator pattern. It includes a number of breaking |
| 103 | +changes, outlined in this section. |
| 104 | + |
| 105 | +- You no longer need a `Zend\ServiceManager\Config` object to configure the |
| 106 | + service manager; you can pass the configuration array directly instead. |
| 107 | + |
| 108 | + In version 2.x: |
| 109 | + |
| 110 | + ```php |
| 111 | + $config = new \Zend\ServiceManager\Config([ |
| 112 | + 'factories' => [...] |
| 113 | + ]); |
| 114 | + |
| 115 | + $sm = new \Zend\ServiceManager\ServiceManager($config); |
| 116 | + ``` |
| 117 | + |
| 118 | + In ZF 3.x: |
| 119 | + |
| 120 | + ```php |
| 121 | + $sm = new \Zend\ServiceManager\ServiceManager([ |
| 122 | + 'factories' => [...] |
| 123 | + ]); |
| 124 | + ``` |
| 125 | + |
| 126 | + `Config` and `ConfigInterface` still exist, however, but primarily for the |
| 127 | + purposes of codifying and aggregating configuration to use. |
| 128 | + |
| 129 | +- `ConfigInterface` has two important changes: |
| 130 | + - `configureServiceManager()` now **must** return the updated service manager |
| 131 | + instance. |
| 132 | + - A new method, `toArray()`, was added, to allow pulling the configuration in |
| 133 | + order to pass to a ServiceManager or plugin manager's constructor or |
| 134 | + `configure()` method. |
| 135 | + |
| 136 | +- Interfaces for `FactoryInterface`, `DelegatorFactoryInterface` and |
| 137 | + `AbstractFactoryInterface` have changed. All are now directly invokable. This |
| 138 | + allows a number of performance optimization internally. |
| 139 | + |
| 140 | + Additionally, all signatures that accepted a "canonical name" argument now |
| 141 | + remove it. |
| 142 | + |
| 143 | + Most of the time, rewriting a factory to match the new interface implies |
| 144 | + replacing the method name by `__invoke`, and removing the canonical name |
| 145 | + argument if present. |
| 146 | + |
| 147 | + For instance, here is a simple version 2.x factory: |
| 148 | + |
| 149 | + ```php |
| 150 | + class MyFactory implements FactoryInterface |
| 151 | + { |
| 152 | + function createService(ServiceLocatorInterface $sl) |
| 153 | + { |
| 154 | + // ... |
| 155 | + } |
| 156 | + } |
| 157 | + ``` |
| 158 | + |
| 159 | + The equivalent version 3 factory: |
| 160 | + |
| 161 | + ```php |
| 162 | + class MyFactory implements FactoryInterface |
| 163 | + { |
| 164 | + function __invoke(ServiceLocatorInterface $sl, $requestedName) |
| 165 | + { |
| 166 | + // ... |
| 167 | + } |
| 168 | + } |
| 169 | + ``` |
| 170 | + |
| 171 | + Note another change in the above: factories also receive a second parameter, |
| 172 | + enforced through the interface, that allows you to easily map multiple service |
| 173 | + names to the same factory. |
| 174 | + |
| 175 | + To provide forwards compatibility, the original interfaces have been retained, |
| 176 | + but extend the new interfaces (which are under new namespaces). You can implement |
| 177 | + the new methods in your existing v2 factories in order to make them forwards |
| 178 | + compatible with v3. |
| 179 | + |
| 180 | +- The for `AbstractFactoryInterface` interface renames the method `canCreateServiceWithName()` |
| 181 | + to `canCreate()`, and merges the `$name` and `$requestedName` arguments. |
| 182 | + |
| 183 | +- Plugin managers will now receive the parent service locator instead of itself |
| 184 | + in factories. In version 2.x, you needed to call the method |
| 185 | + `getServiceLocator()` to retrieve the parent (application) service locator. |
| 186 | + This was confusing, and not IDE friendly as this method was not enforced |
| 187 | + through the interface. |
| 188 | + |
| 189 | + In version 2.x, if a factory was set to a service name defined in a plugin manager: |
| 190 | + |
| 191 | + ```php |
| 192 | + class MyFactory implements FactoryInterface |
| 193 | + { |
| 194 | + function createService(ServiceLocatorInterface $sl) |
| 195 | + { |
| 196 | + // $sl is actually a plugin manager |
| 197 | + |
| 198 | + $parentLocator = $sl->getServiceLocator(); |
| 199 | + |
| 200 | + // ... |
| 201 | + } |
| 202 | + } |
| 203 | + ``` |
| 204 | + |
| 205 | + In version 3: |
| 206 | + |
| 207 | + ```php |
| 208 | + class MyFactory implements FactoryInterface |
| 209 | + { |
| 210 | + function __invoke(ServiceLocatorInterface $sl, $requestedName) |
| 211 | + { |
| 212 | + // $sl is already the main, parent service locator. If you need to |
| 213 | + // retrieve the plugin manager again, you can retrieve it through the |
| 214 | + // servicelocator: |
| 215 | + $pluginManager = $sl->get(MyPluginManager::class); |
| 216 | + // ... |
| 217 | + } |
| 218 | + } |
| 219 | + ``` |
| 220 | + |
| 221 | + In practice, this should reduce code, as dependencies often come from the main |
| 222 | + service locator, and not the plugin manager itself. |
| 223 | + |
| 224 | + To assist in migration, the method `getServiceLocator()` was added to `ServiceManager` |
| 225 | + to ensure that existing factories continue to work; the method emits an `E_USER_DEPRECATED` |
| 226 | + message to signal developers to update their factories. |
| 227 | + |
| 228 | +- `PluginManager` now enforces the need for the main service locator in its |
| 229 | + constructor. In v2.x, people often forgot to set the parent locator, which led |
| 230 | + to bugs in factories trying to fetch dependencies from the parent locator. |
| 231 | + Additionally, plugin managers now pull dependencies from the parent locator by |
| 232 | + default; if you need to pull a peer plugin, your factories will now need to |
| 233 | + pull the corresponding plugin manager first. |
| 234 | + |
| 235 | + If you omit passing a service locator to the constructor, your plugin manager |
| 236 | + will continue to work, but will emit a deprecation notice indicatin you |
| 237 | + should update your initialization code. |
| 238 | + |
| 239 | +- It's so fast now that your app will fly! |
| 240 | + |
5 | 241 | ## 2.7.0 - 2016-01-11 |
6 | 242 |
|
7 | 243 | ### Added |
|
0 commit comments