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 an= d terminology changes, it also have a sub page comparing 4.x with 5.x.
Looking for 4.x documentation ?
You will find the 4.x documentation in the legacy part of the documentation.
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 item still doesn't&nbs=
p;have a corresponding Twig template/controller, eZ Publish will always fallback to the legacy kerne=
l, looking for a legacy template .
If you don't have anything (e.g. pagelayout, config...) mig=
rated to Symfony stack, including Twig templates and Symfony controllers, <=
strong>it's usually better performance wise to use pure legacy stack, using ezpublish_legacy/ folder as your DocumentRoot.
This way you will only use the legacy kernel and eZ Publish will have th= e same behavior as 4.x. However, note that you won't be able to use= the Symfony stack features at all.
Symfony routes are disabled in legacy mode, which impli= es admin interface as well.
If for some reason you need a Symfony route to work, you add it to a whi= telist :
ez_publish_legacy:
# Routes that are allowed when legacy_mode is true.
# Must be routes identifiers (e.g. "my_route_name").
# Can be a prefix, so that all routes beginning with given prefix will =
be taken into account.
legacy_aware_routes: ["my_route_name", "my_route_prefix_"]=20
Deprecation warning
Configuration for legacy aware routes have changed as of 5.4.2. Prior to= this version, configuration was the following:
ezpublish:
router:
default_router:
# Routes that are allowed when legacy_mode is true.
# Must be routes identifiers (e.g. "my_route_name").
# Can be a prefix, so that all routes beginning with given pref=
ix will be taken into account.
legacy_aware_routes: ["my_route_name", "my_route_prefix_"]=20
Note that this notation doesn't work as of eZ Platform (kernel v6.0)
By default, _ezpublishLegacyTreeMenu and all REST v2 (=
ezpublish_rest_ prefix) routes are allowed.
It is possible to include old templates (.tpl) in= to 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 used, exposing all public properties and getters. Yo=
u can define your own converter by implementing the appropriate interface and declare it as a service with the&nb=
sp; ezpublish_legacy.templating.converter ta=
g.
Content / Location objects from the Public API=
are converted into eZContentObj=
ect/eZContentObjectTreeNode objects (re-fetched).&n=
bsp;
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.
All calls from Platform/Symfony stack to legacy stack should be run=
inside a runCallback() call.
<?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 your module uses ezjscore to insert CSS or JS, you need to add calls = to ez_legacy_render_js and= /or ez_legacy_render_css = to the twig template rendering the <head> of your page.
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 Symf=
ony stack cannot be used (i.e. HTTP cache purge) and cache clearing. NB: So=
me script we know won't affect cache, are still documented to be executed t=
he direct way.
Legacy scripts ca=
n be executed form the Symfony CLI, by using the ezpublish:legacy:script command, specifying the pa=
th 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 --env=3Dprod ezpublish:legacy:script bin/php/ezp= generateautoloads.php=20
Here we made sure to specify = --env=3Dprod, this is needed for all legacy scripts that clear cache, other= wise they will will clear dev environment cache instead of prod for Symfony= stack.
Options and arguments
Always pass the legacy script options and arguments AFTER script path, otherwise they will be lost.
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 add=
ed before the path to the script for this to work.
Here's an example:
php ezpublish/console --env=3Dprod ezpublish:legacy:script --legacy-he= lp bin/php/ezpgenerateautoloads.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 --env=3Dprod 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.
Available starting from v5.3 / 2014.03.
Most customization work on eZ Publish legacy was done through Extensions= . Due to the current dual-kernel architecture, many features written for th= e new stack will require some matching legacy code (a FieldType will requir= e the equivalent datatype, a feature might require back-office customizatio= n...). In order to facilitate this, legacy bundles were implemented.
They allow you to place a legacy extension (or several) within a Symfony=
2 bundle. Any such extension will be installed inside ezpublish=
_legacy/extension, and automatically enabled as long as the bundle i=
s registered.
Example: https://github.com/ezsystems/Comment= sBundle
Legacy extensions must:
ezpublish_legacy subfolderAcme/AcmeBundle/ezpublish_legacy/acmeextensionextension.xml fileA symlink (by default) will be created in ezpublish_legacy/extensi=
on pointing to the acmeextension folder. Starting =
from there, it will behave like any regular legacy extension.
Example: https://github.com/ezsystems/= ngsymfonytools-bundle.
An alternative use-case is also covered: you have an existing legacy ext= ension, and a new stack bundle depends on it. It is possible to reference t= his legacy extension, without copying anything from it, and have it automat= ically installed and enabled when the bundle is installed and registered.
To do so, the bundle's Bundle class must implement an extra interface,&n=
bsp;eZ\Bundle\EzPublishLegacyBundle\LegacyBundles\LegacyBundleInterfa=
ce . This interface specifies a getLegacyExtensions=
Names() method, that is expected to return an array of legacy extens=
ions names. Those legacy extension names will be enabled in legacy.<=
/p>
In ngsymfonytoolsbundle, we have two things:
composer.json requires the legacy extensiongetLegacyExtens=
ionsNames(), and returns array( 'ngsymfonytools' ), aut=
omatically enabling the extension in legacy.By default, ezpublish-community/composer.json will call the=
legacy bundle install script after update and install. If for some reason,=
you want to do it manually, it looks a lot like asset install scripts:
php ezpublish/console ezpublish:legacybundles:install_extensions=20
By default, it will create an absolute symlink, but options exist =
to use a hard copy (=E2=80=93copy) or a relative link (
The script will also avoid overwriting existing =
targets if they aren't links to the bundle. The --force option will make the script erase=
existing targets before copying/linking.