To Version 3

Upgrading Applications

If you have an existing Zend Framework v2 application, and want to update it tothe latest versions, you will have some special considerations.

Upgrading Zend Framework

Since the 2.5 release, the zendframework package has been essentially a"metapackage", defining no code, and only dependencies on the various componentpackages. This means that when you installzendframework/zendframework, youget the full set of components, at the latest 2.* versions.

With the release of version 3, we recommend:

• Removing the zendframework/zendframework package.
• Installing the zendframework/zend-component-installer package.
• Installing the zendframework/zend-mvc package.
• Installing each ZF component package you actually use in your application.

The process would look like this:

$ composer remove zendframework/zendframework$ composer require zendframework/zend-component-installer$ composer require zendframework/zend-mvc# Repeat as necessary for components you use if not already installed

When you install zend-mvc, it will prompt you to add configuration forcomponents; choose eitherapplication.config.php ormodules.config.php, andre-use your selection for all other packages. This step ensures that the variouscomponents installed, and any news ones you add later, are configured in yourapplication correctly.

This approach will ensure you are only installing what you actually need. As anexample, if you are not using zend-barcode, or zend-permissions-acl, orzend-mail, there's no reason to install them.

Keeping the zendframework package

If you want to upgrade quickly, and cannot easily determine which components youuse in your application, you can upgrade your zendframework requirement. Whenyou do, you should also install the zend-component-installer, to ensure thatcomponent configuration is properly injected in your application.

$ composer require zendframework/zend-component-installer "zendframework/zendframework:^3.0"

During installation, it will prompt you to add configuration forcomponents; choose eitherapplication.config.php ormodules.config.php, andre-use your selection for all other packages. This step ensures that the variouscomponents installed, and any news ones you add later, are configured in yourapplication correctly.

This will upgrade you to the latest releases of all Zend Framework components atonce; it will also install new components developed as part of the version 3initiative.

We still recommend reducing your dependencies at a later date, however.

Integration packages

During the Zend Framework 3 initiative, one goal was to reduce the number ofdependencies for each package. This affected the MVC in particular, as a numberof features were optional or presented deep integrations between the MVC andother components. These include the following:

Console tooling

If you were using the MVC console tooling, and are doing a partial update perthe recommendations, you will need to installzend-mvc-console.

Forms integration

If you were using the forms in your MVC application, and are doing a partialupdate per the recommendations, you will need to installzend-mvc-form.

i18n integration

If you were using i18n features in your MVC application, and are doing a partialupdate per the recommendations, you will need to installzend-mvc-i18n.

Plugins

If you were using any of theprg(),fileprg(),identity(), orflashMessenger() MVC controller plugins, and are doing a partial update perthe recommendations, you will need to installzend-mvc-plugins.

zend-di integration

If you were using the zend-servicemanager <-> zend-di integration withinyour application, you will need to installzend-servicemanager-di.

Autoloading

If you are doing a partial upgrade per the above recommendations (vs. upgradingthe full zendframework package), one change is that zend-loader is no longerinstalled by default, nor recommended. Instead, we recommend usingComposer for autoloading.

As such, you will need to setup autoloading rules for each module specific toyour application.

As an example, if you are still defining the defaultApplication module, youcan add autoloading for it as follows in your project'scomposer.json:

"autoload": {    "psr-4": {        "Application\\": "module/Application/src/Application/"    },    "files":  [        "module/Application/Module.php"    ]}

The above creates aPSR-4 autoloading rulefor theApplication module, telling it to look in themodule/Application/src/Application/ directory. Since theApplication\Moduleclass is defined at the module root, we specify it in thefiles configuration.

To improve on this, and simplify autoloading, we recommend adopting a completePSR-4 directory structure for your module class files. As an example, to changethe existingApplication module to PSR-4, you can do the following:

$ cd module/Application$ mv src temp$ mv temp/Application src$ rm -Rf ./temp$ mv Module.php src/

Update yourModule.php file to do the following:

• Remove thegetAutoloaderConfig() method entirely, if defined.
• Update thegetConfig() method frominclude __DIR__ . '/config/module.config.php toinclude _DIR__ . '/../config/module.config.php.

You can then update theautoload configuration to:

"autoload": {    "psr-4": {        "Application\\": "module/Application/src/"    }}

Afterwards, run the following to update the generated autoloader:

$ composer dump-autoload

The updated application skeleton already takes this approach.

Bootstrap

Because version 3 requires usage of Composer for autoloading, you can simplifyyour application bootstrap.

First, if you were using aninit_autoloader.php file, you can now remove it.

Second, update yourpublic/index.php to read as follows:

<?phpuse Zend\Mvc\Application;/** * This makes our life easier when dealing with paths. Everything is relative * to the application root now. */chdir(dirname(__DIR__));// Decline static file requests back to the PHP built-in webserverif (php_sapi_name() === 'cli-server') {    $path = realpath(__DIR__ . parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH));    if (__FILE__ !== $path && is_file($path)) {        return false;    }    unset($path);}// Composer autoloadinginclude __DIR__ . '/../vendor/autoload.php';if (! class_exists(Application::class)) {    throw new RuntimeException(        "Unable to load application.\n"        . "- Type `composer install` if you are developing locally.\n"    );}// Run the application!Application::init(require __DIR__ . '/../config/application.config.php')->run();

Scripts

The skeleton application for version 2 shipped three scripts with it:

• bin/classmap_generator.php
• bin/pluginmap_generator.php
• bin/templatemap_generator.php

If you are upgrading an existing application, these will still be present.However, if you are starting a new application, and used these previously, theyare no longer present.

• classmap_generator.php was removed as it's unnecessary when using Composer for autoloading. When preparing a production installation, runcomposer dump-autoload -o and/orcomposer dump-autoload -a; both will generate optimized class map autoloading rules for you.
• pluginmap_generator.php was essentially obsolete due to the presence ofclassmap_generator.php anyways.
• templatemap_generator.php was moved to the zend-view component with the 2.8.0 release of that component, and is now available via./vendor/bin/templatemap_generator.php. Additionally, its usage signature has changed; please use the--help or-h switches on first invocation to discover how to use it.

Development mode

Version 3 of the skeleton application adds a requirement onzfcampus/zf-development-mode,which provides a way to store common development-specific settings in yourrepository and then selectively enable/disable them during development.

If you are upgrading from an existing application, you can install this feature:

$ composer require zfcampus/zf-development-mode

Please refer to thepackage documentationfor details on how to setup your application configuration to make use of thisfeature.