Migration

Upgrading to 3.0

With the release of Laminas, all components current at that time, regardless of history, were tagged as v2 releases; in reality, it was the first version of a new framework, as it was a completely new architecture from Laminas Framework 1. As such, laminas-mvc 3.0 marks the second major release of the component.

The primary goal for version 3 was to reduce the number of dependencies, and to split out unrelated, tangential, or extension functionality. As such, there are a number of changes that will impact users.

Dependency reduction

In order to remove dependencies, we needed to provide alternate ways to ensure that default functionality, such as service registration and event listener attachment, could still occur.

The solution to this problem was to expose each component as a module. This however, raised another problem: you now have to register components as modules in your application.

To solve this new problem, we created a new component, laminas-component-installer. Install this in your application now:

$ composer require --dev laminas/laminas-component-installer

Once installed, the component acts as a Composer plugin, and will intercept packages marked as components or Laminas modules, and register them with your application configuration. Components are pushed to the top of the module list, while modules are pushed to the end. As a development component, it will not be installed in your production distributions.

Updated dependencies

The v3 release now requires:

• laminas-http
• laminas-modulemanager
• laminas-router
• laminas-view

Additionally, the following components require their v3 releases:

• laminas-eventmanager
• laminas-servicemanager
• laminas-stdlib

The minimum supported PHP version was bumped to 5.6.

Application class

The following changes were made to the Laminas\Mvc\Application constructor:

• The first $configuration argument was removed, as it was not used.
• Three additional, optional arguments were added:
• Laminas\EventManager\EventManagerInterface $events = null
• Laminas\Stdlib\RequestInterface $request = null
• Laminas\Stdlib\ResponseInterface $response = null

End-users using the skeleton application and the default Application factory will not notice a change. Those who are directly instantiating the Application instance (in production or test code) or who have created their own factory for the class will need to update their code.

send method

The send() method has been deprecated since the 2.2 release, and a no-op since then as well. It is removed starting with the v3 release.

ControllerLoader

The ControllerLoader service was deprecated early in the v2 lifecycle, and aliased to ControllerManager. The ControllerLoader factory was kept to prevent BC breaks due to extending the class.

v3 removes the ControllerLoaderFactory, as well as the ControllerLoader service alias.

DI-ServiceManager integration

The integration between laminas-servicemanager and laminas-di has been moved to a new standalone component, laminas-servicemanager-di. In most cases, installing the component will restore the original behavior:

$ composer require laminas/laminas-servicemanager-di

Manual installation

The above assumes you're using the new component installer detailed in the dependency reduction section, above. If you are not, you will need to inject the laminas-servicemanager-di module into your application manually; follow the instructions in the laminas-servicemanager-di documentation to do so.

The new component also contains a migration document detailing potential issues for users migrating to version 3.

DispatchListener

The marshallControllerNotFoundEvent() method was deprecated early in the Laminas lifecycle, and has proxied to marshalControllerNotFoundEvent(). It is removed with the v3 release.

Routing

Routing was removed from laminas-mvc, and moved to a new component, laminas-router, which is now a dependency of laminas-mvc.

The changes that will impact users are:

• Query route removal; this route had been deprecated since 2.3.0, and removed for the 3.0 release.
• Namespace changes; with the separation to the laminas-router component, all routes changed namespaces from Laminas\Mvc\Router to Laminas\Router.

Follow the links above for more details on these changes, and how to migrate your code.

Console tooling

Console tooling, including console routes, were split off to a new component, laminas-mvc-console. If you were using the console tooling, install laminas-mvc-console:

$ composer require laminas/laminas-mvc-console

(Make sure you've already installed laminas-component-installer before you do, to ensure the component is registered with your application!)

laminas-mvc-console exposes all of the same functionality as was in the v2 series of laminas-mvc, but most components are in different namespaces. Please read the laminas-mvc-console migration guide for full details of what changes you may need to make to your application to ensure console tooling continues to work.

Migrate your console tooling

Due to the amount of integration required to support console tooling via the MVC, we do not plan on supporting laminas-mvc-console long-term. As such, we recommend migrating your code to use standalone tools such as zf-console or Aura.Cli.

Filter integration

In version 2, laminas-mvc exposed a FilterManager service by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide filter configuration.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-filter component itself. To add it, install laminas-filter:

$ composer require laminas/laminas-filter

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

Form integration

In version 2, laminas-mvc exposed several facilities related to laminas-form:

• FormElementManager mapped to a factory in laminas-mvc, but created a Laminas\Form\FormElementManager instance.
• FormAnnotationBuilder mapped to a factory in laminas-mvc, but created a Laminas\Form\Annotation\AnnotationBuilder instance.
• The ServiceListenerFactory registered Laminas\Form\FormAbstractServiceFactory as an abstract factory.
• The ModuleManagerFactory registered specifications with the laminas-modulemanager ServiceListener to allow modules to provide form element configuration.

The above functionality is now removed from laminas-mvc, and exposed directly by the laminas-form component. To add/enable it, install laminas-form:

$ composer require laminas/laminas-form

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

Hydrator integration

In version 2, laminas-mvc exposed a HydratorManager service by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide hydrator configuration.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-hydrator component itself. To add it, install laminas-hydrator:

$ composer require laminas/laminas-hydrator

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

InputFilter integration

In version 2, laminas-mvc exposed a InputFilterManager service by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide validator configuration.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-inputfilter component itself. To add it, install laminas-inputfilter:

$ composer require laminas/laminas-inputfilter

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

laminas-inputfilter now also exposes the InputFilterAbstractServiceFactory as an abstract factory by default.

i18n integration

Internationalization tooling, including:

• the integration translator (MvcTranslator service)
• the "dummy" translator
• the TranslatorAwareTreeRouteStack implementation
• factories for the translator and translator loader managers

were removed, and re-assigned to the laminas-i18n and laminas-mvc-i18n packages. In most cases, you can install laminas/laminas-mvc-i18n to restore i18n functionality to your application:

$ composer require laminas/laminas-mvc-i18n

There are two categories of changes that could affect you on upgrading.

First, if you were using the TranslatorAwareTreeRouteStack, the class name has changed from Laminas\Mvc\Router\Http\TranslatorAwareTreeRouteStack to Laminas\Mvc\I18n\Router\TranslatorAwareTreeRouteStack; updating your code to reflect that will allow it to work again.

Second, if you were extending one of the service factories for either the MvcTranslator or the TranslatorPluginManager, the namespaces for the factories have changed. In such situations, you have two options:

• Update your extensions to extend the new classes. See the laminas-mvc-i18n migration guide to determine what names have changed.
• Instead of extending, consider using delegator factories, as these decorate the service factory, regardless of what factory is used.

Log integration

In version 2, laminas-mvc exposed LogProcessorManager and LogWriterManager services by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide configuration for each.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-log component itself. To add it, install laminas-log:

$ composer require laminas/laminas-log

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

laminas-log now also exposes LogFilterManager and LogFormatterManager, corresponding to the following:

This additions allow you to provide additional plugins for every aspect laminas-log exposes.

Plugins

The following plugins have been removed from the main laminas-mvc repository, and into their own standalone repositories. In all cases, please be sure to install the component installer as detailed above before installing the plugins, to automate injection into your application configuration.

fileprg()

The fileprg() plugin is now provided via the laminas-mvc-plugin-fileprg component.

$ composer require laminas/laminas-mvc-plugin-fileprg

Laminas\Mvc\Controller\Plugin\FilePostRedirectGet becomes Laminas\Mvc\Plugin\FilePrg\FilePostRedirectGet. However, it is still mapped as fileprg().

flashMessenger()

The flashMessenger() plugin is now provided via the laminas-mvc-plugin-flashmessenger component.

$ composer require laminas/laminas-mvc-plugin-flashmessenger

Laminas\Mvc\Controller\Plugin\FlashMessenger becomes Laminas\Mvc\Plugin\FlashMessenger\FlashMessenger. However, it is still mapped as flashMessenger() and flashmessenger().

identity()

The identity() plugin is now provided via the laminas-mvc-plugin-identity component.

$ composer require laminas/laminas-mvc-plugin-identity

Laminas\Mvc\Controller\Plugin\Identity becomes Laminas\Mvc\Plugin\Identity\Identity. However, it is still mapped as identity().

Additionally, Laminas\Mvc\Controller\Plugin\Service\IdentityFactory now becomes Laminas\Mvc\Plugin\Identity\IdentityFactory.

prg()

The prg() plugin is now provided via the laminas-mvc-plugin-prg component.

$ composer require laminas/laminas-mvc-plugin-prg

Laminas\Mvc\Controller\Plugin\PostRedirectGet becomes Laminas\Mvc\Plugin\Prg\PostRedirectGet. However, it is still mapped as prg().

Serializer integration

In version 2, laminas-mvc exposed a SerializerAdapterManager service by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide serializer configuration.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-serializer component itself. To add it, install laminas-serializer

$ composer require laminas/laminas-serializer

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

ServiceLocatorAware initializers

Starting with laminas-servicemanager v3, that component no longer defines the ServiceLocatorAwareInterface. Since laminas-mvc pins against laminas-servicemanager v3 with its own v3 release, the initializers that injected the application container into implementations of that interface are no longer relevant. As such, they have now been removed from each of the Laminas\Mvc\Service\ServiceManagerConfig and Laminas\Mvc\Controller\ControllerManager classes.

Additionally, the duck-typed ServiceLocatorAwareInterface implementation in AbstractController was removed, as messaged in the 2.7 release.

If you relied on this functionality, you are encouraged to update your code to use factories to inject your actual dependencies.

Validator integration

In version 2, laminas-mvc exposed a ValidatorManager service by default, and provided specifications to laminas-modulemanager's ServiceListener to allow modules to provide validator configuration.

This functionality is now removed from laminas-mvc. It is now exposed directly by the laminas-validator component itself. To add it, install laminas-validator:

$ composer require laminas/laminas-validator

Note: the above assumes you have already installed laminas-component-installer, per the section above on dependency reduction.

Laminas\Mvc\View\InjectTemplateListener

The InjectTemplateListener attempts to map a controller name to a template using a variety of heuristics, including an explicit map provided during configuration, or auto-detection based on the controller class name.

In version 2, the autodetection took into consideration the __NAMESPACE__ route match parameter to derive subnamespaces, or would omit them completely if __NAMESPACE__ was not present. This caused issues when multiple modules shared a top-level namespace (e.g., Laminas\ApiTools and Laminas\ApiTools\Admin) and each had a controller with the same name.

To avoid naming conflicts, version 3 removes this aspect of autodetection, and instead provides exactly one workflow for mapping:

• Strip the Controller subnamespace, if present (e.g., the namespace Application\Controller\\ is normalized to Application\\).
• Strip the Controller suffix in the class name, if present (e.g., IndexController is normalized to Index).
• Inflect CamelCasing to dash-separated (e.g., ShowUsers becomes show-users).
• Replace the namespace separator with a slash.

As a full example, the controller service name TestSomething\With\Controller\CamelCaseController will always map to test-something/with/camel-case, regardless of the __NAMESPACE__ value provided in routing configuration.

If needed, you can emulate the version 2 behavior in version 3 via namespace whitelisting in the controller <=> template map.

Laminas\Mvc\View\SendResponseListener

Laminas\Mvc\View\SendResponseListener was deprecated with the 2.2 release, and has been an extension of Laminas\Mvc\SendResponseListener ever since. It is removed with the v3 release.