Back to Blog
How to's

Migrating Dotkernel 3 from Zend Expressive 2 to Zend Expressive 3

By Gabi DJ Jun 13, 2018

Packages

In composer.json replace the matching repositories with the following:

"dotkernel/dot-authentication-service":"^1.0",
"dotkernel/dot-authentication-service":"^1.0",
"dotkernel/dot-authentication-web":"^1.0.1",
"dotkernel/dot-authentication":"^1.0",
"dotkernel/dot-authorization":"^0.1.2",
"dotkernel/dot-controller":"^1.0",
"dotkernel/dot-controller-plugin-authentication":"^1.0",
"dotkernel/dot-controller-plugin-authorization":"^1.0",
"dotkernel/dot-controller-plugin-forms":"^1.0",
"dotkernel/dot-controller-plugin-flashmessenger":"^1.0",
"dotkernel/dot-controller-plugin-mail":"^1.0",
"dotkernel/dot-controller-plugin-session":"^1.0",
"dotkernel/dot-form":"^1.1.1",
"dotkernel/dot-filter":"^1.1.1",
"dotkernel/dot-flashmessenger":"^1.0",
"dotkernel/dot-helpers":"^1.0",
"dotkernel/dot-inputfilter":"^1.1",
"dotkernel/dot-mail":"^1.0",
"dotkernel/dot-mapper":"^1.0",
"dotkernel/dot-navigation":"^1.0",
"dotkernel/dot-rbac-guard":"^1.0",
"dotkernel/dot-session":"^3.0",
"dotkernel/dot-twigrenderer":"^1.1",
"dotkernel/dot-user":"^1.0",
"dotkernel/dot-rbac":"^0.2.1",
"dotkernel/dot-validator":"^1.1",

"zendframework/zend-escaper":"^2.6",
"zendframework/zend-expressive-helpers":"^5.0",
"zendframework/zend-expressive-twigrenderer":"^2.0",
"zendframework/zend-expressive-template":"^2.0",
"zendframework/zend-expressive":"^3.0",
"zendframework/zend-expressive-fastroute":"^3.0",
"zendframework/zend-expressive-tooling":"^1.0",
"zendframework/zend-expressive-router":"^3.0",
"zendframework/zend-stratigility":"^3.0",
"zendframework/zend-component-installer":"^2.0

Also update require-dev dependencies:

"zendframework/zend-expressive-tooling:": "^1.0",
"zendframework/zend-component-installer": "^2.0",

Remove packages:

  • http-interop/http-middleware
  • webimpress/http-middleware-compatibility

Configurations

Main Configuration

In config/config.php add the following config providers:

// zend expressive & middleware factory
\Zend\Expressive\ConfigProvider::class,

// router config
\Zend\Expressive\Router\ConfigProvider::class,
\Zend\Expressive\Router\FastRouteRouter\ConfigProvider::class,

\Zend\Expressive\Twig\ConfigProvider::class,
\Zend\Expressive\Helper\ConfigProvider::class,

// handler runner
\Zend\HttpHandlerRunner\ConfigProvider::class,

Make sure they are the first ConfigProviders or before cached config (ArrayProvider).

Routing

Wrap routing from config/routes.php in a callable with the following format:

return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    /** @var \Zend\Expressive\Application $app */
    $app->route('/', , , 'home');
};

Add the following use statements and make sure the names are not duplicate:

use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\MiddlewareFactory;

Pipeline

Wrap routing from config/pipeline.php in a callable with the following format:

return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    /** @var \Zend\Expressive\Application $app */
    $app->route('/', , , 'home');
};

Add the following use statements and make sure the names are not duplicate:

use Psr\Container\ContainerInterface;
use Zend\Expressive\Application;
use Zend\Expressive\MiddlewareFactory;

Routing Middleware Migration

Add the following use statements:

use Zend\Expressive\Router\Middleware\RouteMiddleware;
use Zend\Expressive\Router\Middleware\DispatchMiddleware;

Replace the following lines to reflect the changes:

  • $app->pipeRoutingMiddleware(); becomes $app->pipe(RouteMiddleware::class);
  • $app->pipeDispatchMiddleware(); becomes $app->pipe(DispatchMiddleware::class);

You can check the complete guides and example files from the following links:

Frequently Asked Questions

What should you read before starting the migration? +

For a better understanding of the migration and how it affects support, it's recommended to read Zend Expressive's article on migration regarding HTTP interop.

What happens to old middleware during the migration? +

If a project contains old middleware, it must be refactored to reflect the interfaces provided in the psr/http-server-middleware package. As part of this, Delegates become RequestHandlers, using interfaces from the psr/http-server-handler package.

Which packages should be removed during migration? +

http-interop/http-middleware and webimpress/http-middleware-compatibility should be removed from composer.json.

What needs to be added to the main configuration file? +

In config/config.php, several ConfigProviders need to be added - for Zend Expressive, the router, FastRoute router, Twig, helpers, and the handler runner - and they must be the first ConfigProviders or placed before the cached config (ArrayProvider).

How do the routes.php and pipeline.php files change? +

Routing from config/routes.php and the pipeline from config/pipeline.php both need to be wrapped in a callable of the form function (Application $app, MiddlewareFactory $factory, ContainerInterface $container), with the corresponding use statements added.

What replaces pipeRoutingMiddleware() and pipeDispatchMiddleware()? +

$app->pipeRoutingMiddleware(); becomes $app->pipe(RouteMiddleware::class);, and $app->pipeDispatchMiddleware(); becomes $app->pipe(DispatchMiddleware::class);.