Legacy bundles

Audience: integrators, extension developers Author: Bertrand Dunogier bertrand.dunogier@ez.no Created: 22/01/2014 JIRA story: https://jira.ez.no/browse/EZP-22210 Topics: BC, Extensibility

Summary

Make it possible to ship legacy extensions in a Symfony 2 bundle.

Bundles can provide legacy extensions in two ways:

Shipping legacy extensions within a bundle

Legacy extensions are stored within the bundle, in an ezpublish_legacy folder.

Each extension has its own subdirectory containing at least an extension.xml file.

Enabling extensions the bundle depends on

If a legacy extension already exists, it can be added to the bundle's composer.json file as a requirement. To automatically enable such an extension, the bundle's class must implement eZ\Bundle\EzPublishLegacyBundle\LegacyBundles\LegacyBundleInterface, and return the legacy extension name in an array.

# vendor/acme/LegacyBundle/composer.json
"requires:" {
    "acme/acmeextension": "~1.0"
}

// vendor/acme/LegacyBundle/AcmeLegacyBundle.php
namespace Acme\LegacyBundle;

use eZ\Bundle\EzPublishLegacyBundle\LegacyBundles\LegacyBundleInterface;

class AcmeLegacyBundle implements LegacyBundleInterface
{
    public function getLegacyExtensionsNames()
    {
        return array( 'acmeextension' );
    }
}

Benefits

• development can be made without actually going inside the ezpublish_legacy folder
• versioning and deployment is easier, since this folder can be created in the project's bundle
• makes up for the non-injection/mapping of a huge part of the legacy configuration by making it visible from the new stack structure
• legacy extensions can very easily be bundled as eZ Publish 5 bundles without changing a single line of code
• the legacy (backoffice) counterpart of new stack extensions can be bundled together with the new stack code, and automatically installed using composer

Use-cases

Custom extension

The developer of a custom extension, like a fieldtype, wants to make his extension available via composer, and add preliminary new stack support to it. He creates a new bundle for his extension, and copies all of its contents to Resources/ezpublish-legacy. Anyone can install his legacy extension by requiring it from composer.json. The custom install script will link it into his legacy extensions folder, and enable it when the bundle is enabled.

Website project configuration

A project's maintainer wants to gather as much as possible of his project elements into one place. Any setting that isn't mapped by the semantical configuration can be overridden using the Resources/ezpublish-legacy folder, using the standard settings/override and settings/siteaccess folder. Custom legacy templates can also be created here, for instance to override a couple backoffice elements.

Dual-kernel extension

Custom FieldType

Since there is no backoffice yet, a couple legacy elements are still required (datatype class, edit/view templates, settings. Using a Bundle, the developer can have both the new stack and legacy code in the same structure, and make sure both evolve at the same rythm:

• Acme/Bundle/AcmeBundle/ezpublish_legacy/acmefieldtype contains the legacy datatype extension
• Acme/Bundle/AcmeBundle/eZ/FieldType contains the new stack implementation

Backoffice customization

If a new stack feature requires custom items in the backoffice, like a content tab, or custom templates, a legacy bundle can be used to keep those elements along with the bundle, and have it automatically installed & enabled as long as the bundle is registered.

Implementation outline

• A symfony script, executed on post-update by composer, links found legacy extensions to the legacy extensions folder.
• In a compiler pass, applicable legacy extensions are scanned from all enabled bundles and stored as container parameters.
• At runtime, a - ezpublish_legacy.legacy_bundles_extensions is merged into injected INI settings to site.ini/ExtensionSettings/ActiveExtensions by a LegacyMapper event

Install script

The script, ezpublish:legacybundles:install_extensions, will symlink into ezpublish_legacy/extensions all extension directories returned by the scanner.

• Symlink will be used by default
• If the target already exists in legacy, it won't be overwritten, and an error will be thrown if the existing item is a physical folder or a link to a different target, unless the --force option is used
• If the --force option is set, any existing target will be removed before creating the link.

The script is executed by composer at post-update/post-install.

Legacy bundles scanning for extensions directories & names

Legacy bundles extension directories are scanned as follows:

• bundles that contain an ezpublish_legacy folder, containing subfolders with an extension.xml file.

The list of actual legacy extensions is the basename() of all extension directories found in the bundles. Additional extensions names can be specified without a physical extension directory. If a bundle implements eZ\Bundle\EzPublishLegacyBundle\LegacyBundles\LegacyBundleInterface, the getLegacyExtensionsNames custom method will be called on it. It must return an array of legacy extension names that need to be enabled.

Extensions names from those bundles are returned by the interface method implemented by the bundle.

Container parameters

Parameter name: ezpublish_legacy.legacy_bundles_extensions.

Legacy injection

Injected settings: site.ini/ExtensionSettings/ActiveExtensions.

Open questions

• What settings can not be overridden this way ?