eZ Publish 5 has a strong focus on backwards compatibility and t= hus lets you reuse code you might have written for 4.x, including templates= and modules.
Hint
Read Intro for= eZ Publish 4.x/3.x developers to have an overview of common concepts a= nd terminology changes.
Legacy mode is a specific configuration mode where eZ Publish's behavior= is the closest to v4.x. It might be used in some very specific use cases, = such as running the admin interface.
In a migration context, using Legacy Mode is never a good option=
as it prevents all the performance goodness (e.g. Http Cache) to =
work.
Always keep in mind that, not running in legacy mode, if a=
content still doesn't have a corresponding Twig template/controller, =
eZ Publish will always =
fallback to the legacy kernel, looking for a legacy template.<=
/p>
It is possible to include old templates (.tpl) into new= ones.
{# Twig template #}
{# Following code will include my/old_template.tpl, exposing $someVar varia=
ble in it #}
{% include "design:my/old_template.tpl" with {"someVar": "someValue"} %}=20
Or if you want to include a legacy template by its path, relative to ezpublish_legacy folder:
{# Following code will include ezpublish_legacyextension/my_legacy_=
extension/design/standard/templates/my_old_template.tpl, exposing $someVar =
variable in it #}
{% include "file:extension/my_legacy_extension/design/standard/templates/my=
_old_template.tpl" with {"someVar": "someValue"} %}=20
Scalar and array parameters are passed to a legacy template as-is.
Objects, however, are being converted in order to comply the legacy eZ Template API. By default a generic adapter is u=
sed, exposing all public properties and getters. You can define your own co=
nverter by implementing the appropriate interface =
and declare it as a service with the ezpublish_legacy.te=
mplating.converter tag.
Content / Location objects from the Public API=
are converted into eZContentObject/<=
code>eZContentObjectTreeNode objects (re-fetched).
eZ Publish 5 still relies on the legacy kernel (from 4.x) and runs it wh=
en needed inside an isolated PHP closure, making it runCallback() method.
<?php
// Declare use statements for the classes you may need
use eZINI;
// Inside a controller extending eZ\Bundle\EzPublishCoreBundle\Controller
$settingName =3D 'MySetting';
$test =3D array( 'oneValue', 'anotherValue' );
$myLegacySetting =3D $this->getLegacyKernel()->runCallback(
function () use ( $settingName, $test )
{
// Here you can reuse $settingName and $test variables inside the l=
egacy context
$ini =3D eZINI::instance( 'someconfig.ini' );
return $ini->variable( 'SomeSection', $settingName );
}
);=20
The example above is very simple and naive - in fact for accessing confi= guration settings from the Legacy Stack using the ConfigResolver is recommended.
Using the legacy closure, you'll be able to even run complex legacy feat= ures, like an eZ Find search:
use eZFunctionHandler;
$searchPhrase =3D 'My search phrase';
$sort =3D array(
'score' =3D> 'desc',
'published' =3D> 'desc'
);
$contentTypeIdenfiers =3D array( 'folder', 'article' );
$mySearchResults =3D $this->getLegacyKernel()->runCallback(
function () use ( $searchPhrase, $sort, $contentTypeIdenfiers )
{
// eZFunctionHandler::execute is the equivalent for a legacy templa=
te fetch function
// The following is the same than fetch( 'ezfind', 'search', hash(.=
..) )
return eZFunctionHandler::execute(
'ezfind',
'search',
array(
'query' =3D> $searchPhrase,
'sort_by' =3D> $sort,
'class_id' =3D> $contentTypeIdenfiers
)
);
}
);=20
Any route that is not declared in eZ Publish 5 in an included
This allows all your old modules to work as before,&nbs= p;out-of-the-box (including kernel modules), and also allows you to reuse t= his code from your templates using sub requests:
{{ render( url( 'ez_legacy', {'module_uri': '/content/view/sit=
emap/2'} ) ) }}=20
If for some reason you need to develop a legacy module and access to eZ = Publish 5 / Symfony features (i.e. when developing an extension for admin i= nterface), you'll be happy to know that you actually have access to all ser= vices registered in the whole framework, including bundles, through the ser= vice container.
The example below shows how to retrieve the content repository and the l= ogger.
// From a legacy module or any PHP code running in legacy context. $container =3D ezpKernel::instance()->getServiceContainer(); /** @var $repository \eZ\Publish\API\Repository\Repository */ $repository =3D $container->get( 'ezpublish.api.repository' ); /** @var $logger \Symfony\Component\HttpKernel\Log\LoggerInterface|\Psr\Log= \LoggerInterface */ // PSR LoggerInterface is used in eZ Publish 5.1 / Symfony 2.2 $logger =3D $container->get( 'logger' );=20
The example above works in legacy modules and CLI scripts
Note: This feature has been introduced in eZ Publish 5.1.
Important
Running legacy scripts and cronjobs through the Symfony stack is=
highly recommended !
Otherwise, features from the Symfony stac=
k cannot be used (i.e. HTTP cache purge) and cache clearing. NB: Some scrip=
t we know won't affect cache, are still documented to be executed the direc=
t way.
Legacy scripts ca=
n be executed form the Symfony CLI, by using the ezpublish:legacy:script command, specifying the path=
to the script as argument.
The command will need to be executed from eZ Publish's 5 root, and the p=
ath to the desired script must exist in the ezpublish_legacy f=
older.
Here's a usage example:
php ezpublish/console ezpublish:legacy:script bin/php/ezpgenerateautol= oads.php=20
If you want to access the script's help please be aware that you will ne=
ed to use the newly introduced --legacy-help option, since --h=
elp is already reserved for the CLI help.
The --legacy-help option should be added before the =
path to the script for this to work.
Here's an example:
php ezpublish/console ezpublish:legacy:script --legacy-help bin/php/ez= pgenerateautoloads.php=20
The same logic will apply for cronjob execution.
Legacy cronjobs are =
triggered by the runcronjobs.php legacy script, which exp=
ects the name of the cronjob to run as a parameter.
This is how you can =
run cronjobs from the Symfony CLI:
php ezpublish/console ezpublish:legacy:script runcronjobs.php frequent==20
Also, if you require using additional script options, please be sure to =
use the long name, such as --siteaccess or --debug to avoid conflicts between script and CLI options.
For more details re=
garding legacy cronjobs execution please refer to the Running cronjobs chapter =
existing in doc.ez.no.