• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
2013.04.23 eZ Sessions 6 - Migrating legacy eZ Publish extensions - Lukasz Serwatka

2013.04.23 eZ Sessions 6 - Migrating legacy eZ Publish extensions - Lukasz Serwatka



Talk given by Lukasz Serwatka during the eZ Session Show, 6th episode, online. Learn more at http://www.meetup.com/eZ-Publish-Users-Developers/events/107927592/ ...

Talk given by Lukasz Serwatka during the eZ Session Show, 6th episode, online. Learn more at http://www.meetup.com/eZ-Publish-Users-Developers/events/107927592/

Meet the eZ Publish Community on http://share.ez.no



Total Views
Views on SlideShare
Embed Views



2 Embeds 188

http://share.ez.no 158
https://twitter.com 30



Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    2013.04.23 eZ Sessions 6 - Migrating legacy eZ Publish extensions - Lukasz Serwatka 2013.04.23 eZ Sessions 6 - Migrating legacy eZ Publish extensions - Lukasz Serwatka Presentation Transcript

    • Migrating eZ Publish 4 extensions to eZ Publish 5
    • 2013-04-23Presenter: Łukasz Serwatka Slide 2Extending eZ Publish 5§PresenterŁukasz SerwatkaProduct Management Technical Leadlukasz.serwatka@ez.no@lserwatka§Working with eZ since 1st of March 2005§Over 10 years of experience with eZ Publish§Former member of the Engineering team§eZ Publish & Polish PHP Community Member§Expert in mobile solutions (mobile applications & mobile strategies)
    • 13-4-26Presenter: Łukasz Serwatka Slide 3Extending eZ Publish 5§Preparation§Drivers for migration (challenges, requirements) - It is very important tounderstand the drivers behind a migration effort§Inventory of current environment - Creating a detailed summary of thecurrent extension portfolio really helps in terms of understanding the scopeof a migration effort§Migration service provider - evaluate at least a couple of migration serviceproviders if you do not have migration skills and staff in-house.§Migration effort estimate - the estimate depends on many factors such asextension size, database complexity, components, etc. Usually provided bythe migration service provider.§Training requirements - Training requirements for existing developmentteam on the new platform need to be assessed to ensure that they cansupport the new environment effectively and can participate in the migrationprocess if required.
    • 13-4-26Presenter: Łukasz Serwatka Slide 4Extending eZ Publish 5§Preparation§Make in-depth analysis of the existing eZ Publish 4.x extension functionalityand code base, focusing especially on§ External storage (custom tables)§ Configuration (INI settings overrides)§ CLI scripts§ Template overrides§ Datatypes§ Edit handlers§ Workflow events§ AJAX calls§ Translations§ User interface (backend)§Carefully judge which elements can be natively implemented in eZ Publish 5and which ones still require legacy kernel. Not all legacy features areavailable in eZ Publish 5 yet, and it is an ongoing process to fill the gaps.
    • 13-4-26Presenter: Łukasz Serwatka Slide 5Extending eZ Publish 5§Preparation§The eZ Publish 5 supported extension points at the moment:§ FieldTypes (with custom tables)§ Templates (view providers for Content, Location and Blocks [since eZ Publish5.1])§ Services (Persistence API)§ Controllers & Actions (Routes)§ Events (PostSiteAccessMatchEvent, PreContentViewEvent,APIContentExceptionEvent)− eZ/Publish/Core/MVC/Legacy/LegacyEvents.php−eZ/Publish/Core/MVC/Symfony/MVCEvents.php
    • 13-4-26Presenter: Łukasz Serwatka Slide 6Extending eZ Publish 5§New concepts in eZ Publish 5.xeZ Publish 4.x eZ Publish 5.xModule Controller, extendseZBundleEzPublishCoreBundleControllerAction & View Action: the method on the Controller toexecute. View is a (Twig) template thatdisplays the result of the Action.eZTemplate Twig, new template engine, new syntaxfetch() Render function, HMVC concept, a functionthat enables embedding if other controllercallsExtension Bundle in the eZ Publish 5 (Symfony2)CLI eZ Publish 5 ezpublish/consolecomponent for creating command lineinterfacesINI settings YAML, recommended configuration type ineZ Publish 5
    • 13-4-26Presenter: Łukasz Serwatka Slide 7Extending eZ Publish 5§Naming differences between eZ Publish 4.x and 5.xeZ Publish 4.x eZ Publish 5.x(Content) Class ContentType(Content) Class Group ContentTypeGroup(Content) Class Attribute FieldDefinition(Content) Object Content (meta info in: ContentInfo)(Content Object) Version VersionInfo(Content Object) Attribute Field(Content Object) Attribute content FieldValueDatatype FieldTypeNode Location
    • §eZ Publish 5 can be extended thanks to the bundle system§A Bundle is a directory containing a set of files (PHP files, stylesheets,JavaScripts, images, ...) that implement a single feature (a blog, a forum, etc)and which can be easily shared with other developers.§eZ Publish 5 also provides a command line interface for generating a basicbundle skeleton:$ php ezpublish/console generate:bundle –namespace=eZ/TestBundle13-4-26Presenter: Łukasz Serwatka Slide 8Extending eZ Publish 5
    • 13-4-26Presenter: Łukasz Serwatka Slide 9Extending eZ Publish 5§Bundle Directory StructureBundle Directory Structure DescriptionController/ contains the controllers of the bundle (e.g.HelloController.php);DependencyInjection/ holds certain dependency injection extension classes,which may import service configurationResources/config/ houses configuration, including routing configuration(e.g. routing.yml);Resources/views/ holds templates organized by controller name (e.g.Hello/index.html.twig);Resources/public/ contains web assets (images, stylesheets, etc) and iscopied or symbolically linked into the project web/directory via the assets:install console command;Tests/ holds all tests for the bundle.
    • 13-4-26Presenter: Łukasz Serwatka Slide 10Extending eZ Publish 5§Bundle Directory Structure – AdvancedBundle Directory Structure DescriptionAPI/ contains the value object definitions, serviceinterfaces, etc. In short, public API interfaces providedby your bundle.Core/ holds field types implementation, persistence relatedclasses, repository implementations, signal-slotimplementations, etc.SPI/ (Service Provider Interface) holds interfaces that cancontains one or several implementations aroundPersistence (database), IO (file system), FieldTypes(former DataTypes), Limitations (permissions system),etc.EventListeners/ holds event listeners implementation for both eZPublish 5 and LSCommand/ contains Console commands, each file must besuffixed with Command.php
    • §Example eZ Publish 5 Bundle architecture13-4-26Presenter: Łukasz Serwatka Slide 11Extending eZ Publish 5§Bundle Directory Structure
    • §File: eZTestBundle.php<?phpNamespace eZTestBundle;use SymfonyComponentHttpKernelBundleBundle;class eZTestBundle extends Bundle{}13-4-26Presenter: Łukasz Serwatka Slide 12Extending eZ Publish 5§Main Bundle Class
    • §Before a Bundle can be used it has to be registered in the system.§With the registerBundles() method, you have total control over which bundlesare used by eZ Publish 5 (including the core Symfony bundles).// ezpublish/EzPublishKernel.phppublic function registerBundles(){$bundles = array(...,// register your bundlesnew eZTestBundleeZTestBundle(),);// ...return $bundles;}13-4-26Presenter: <enter presenter Slide 13Extending eZ Publish 5§Registering Bundle
    • §eZ Publish 5 provides a shortcut for automatic bundle registrationphp ezpublish/console generate:bundle--namespace=eZ/TestBundlephp ezpublish/console assets:install --symlinkphp ezpublish/console cache:clear13-4-26Presenter: Łukasz Serwatka Slide 14Extending eZ Publish 5§Registering Bundle
    • §File: eZTestBundle.php<?phpNamespace eZTestBundle;use SymfonyComponentHttpKernelBundleBundle;class eZTestBundle extends Bundle{public function getParent(){return ’eZDemoBundle;}}13-4-26Presenter: Łukasz Serwatka Slide 15Extending eZ Publish 5§Bundle Override
    • §File: src/eZ/DemoBundle/Controller/MyController.php<?phpnamespace eZDemoBundleMyController;use EzSystemsDemoBundleControllerDemoController as BaseController;class MyController extends BaseController{public function footerAction( $locationId ){// Call parent method or completely replace its logic with your own$response = parent::footerAction( $locationId );// ... do custom stuffreturn $response;}}§Only works if the bundle refers to the controller using the standardEzSystemsDemoBundle:Demo:footer syntax in routes and templates13-4-26Presenter: Łukasz Serwatka Slide 16Extending eZ Publish 5§Controller Override
    • §File: view.html.twig<h1>Hello</h1><p>I’m a Twig template!</p>§Created Twig template can be included as follows:{% include ‘eZTestBundle::view.html.twig’ %}13-4-26Presenter: Łukasz Serwatka Slide 17Extending eZ Publish 5§Example Twig Template
    • §Legacy template include// eZ Publish 5.0{% ez_legacy_include "design:parts/menu.tpl" with{"current_node_id": location.contentInfo.mainLocationId}%}// eZ Publish 5.1 and above{% include "design:parts/menu.tpl" with{"current_node_id": location.contentInfo.mainLocationId}%}Note that if you pass Content or a Location it will be converted to thecorresponding eZ Publish Legacy objects.13-4-26Presenter: Łukasz Serwatka Slide 18Extending eZ Publish 5§Working with legacy templates
    • §The best practice for extension migration regarding configuration is to keep acompatible formatezoe.ini[EditorSettings]# Skin for the editor, default and o2k7 is included as standardSkin=o2k7# Lets you control alignment of toolbar buttons [left|right]ToolbarAlign=leftparameters:# Namespace is ezoe (INI file was ezoe.ini), scope is defined toezdemo_site siteaccessezoe.ezdemo_site.EditorSettings.Skin: o2k7ezoe.ezdemo_site.EditorSettings.ToolbarAlign: left13-4-26Presenter: Łukasz Serwatka Slide 19Extending eZ Publish 5§Working with INI settings
    • // Assuming that the current siteaccess is ezdemo_site// The following code will work whether youre using the legacy extensionor the migrated one.$resolver = $this->getConfigResolver();$skin = $resolver->getParameter( ’EditorSettings.Skin, ’ezoe );$toolbarAlign= $resolver->getParameter( ’EditorSettings.ToolbarAlign,’ezoe );13-4-26Presenter: Łukasz Serwatka Slide 20Extending eZ Publish 5§Working with INI settings
    • §Datatypes are FieldTypes in eZ Publish 5§Extends eZPublishCoreFieldTypeFieldType class§Uses Value objects for storing arbitrary data (extendseZPublishCoreFieldTypeValue)§Requires converters for field values in legacy storage (implementseZPublishCorePersistenceLegacyContentFieldValueConverter)§A NULL Converter is available for developers convenience§Uses gateways for getting data from external storage (custom tables)13-4-26Presenter: Łukasz Serwatka Slide 21Extending eZ Publish 5§FieldType
    • §A common issue with rendering legacy field types in eZ Publish 5 is theAPI_CONTENT_EXCEPTION§It occurs when the API throws an exception that could not be caughtinternally (missing field type, missing converter, internal error...)§For simple field types, declaration of NULL converter is often a resolution// Resources/config/fieldtypes.ymlezpublish.fieldType.ezsample.class: %ezpublish.fieldType.eznull.class%ezpublish.fieldType.ezsample:class: %ezpublish.fieldType.ezsample.class%parent: ezpublish.fieldTypearguments: [ ”ezsample" ]tags:- {name: ezpublish.fieldType, alias: ezsample}13-4-26Presenter: Łukasz Serwatka Slide 22Extending eZ Publish 5§NULL Converter
    • // Resources/config/storage_engines.ymlezpublish.fieldType.ezsample.converter.class:%ezpublish.fieldType.eznull.converter.class%ezpublish.fieldType.ezsample.converter:class: %ezpublish.fieldType.ezsample.converter.class%tags:- {name: ezpublish.storageEngine.legacy.converter, alias:ezsample, lazy: true, callback: ::create}13-4-26Presenter: Łukasz Serwatka Slide 23Extending eZ Publish 5§NULL Converter
    • §Some FieldTypes store data in external data sources§Possible through the eZPublishSPIFieldTypeFieldStorage interface.// Resources/config/fieldtypes.ymlparameters:ezpublish.fieldType.ezsample.externalStorage.class:eZPublishCoreFieldTypeSampleSampleStorageservices:ezpublish.fieldType.ezsample.externalStorage:class: %ezpublish.fieldType.ezsample.externalStorage.class%tags:- {name: ezpublish.fieldType.externalStorageHandler, alias:ezsample}13-4-26Presenter: Łukasz Serwatka Slide 24Extending eZ Publish 5§External storage
    • §It is recommended to use gateway-based storage§Implement a gateway infrastructure and a registry for the gateways§Possible through the eZPublishCoreFieldTypeStorageGateway// Resources/config/fieldtypes.ymlparameters:ezpublish.fieldType.ezsample.storage_gateway.class:eZPublishCoreFieldTypeSampleSampleStorageGatewayLegacyStorageservices:ezpublish.fieldType.ezsample.storage_gateway:class: %ezpublish.fieldType.ezsample.storage_gateway.class%tags:- {name: ezpublish.fieldType.externalStorageHandler.gateway,alias: ezsample, identifier: LegacyStorage}13-4-26Presenter: Łukasz Serwatka Slide 25Extending eZ Publish 5§External storage
    • abstract class Gateway extends StorageGateway{/*** Stores data in the database based on the given field data** @param eZPublishSPIPersistenceContentVersionInfo $versionInfo* @param eZPublishSPIPersistenceContentField $field*/abstract public function storeFieldData( VersionInfo $versionInfo, Field $field );/*** Gets data stored in the field** @param eZPublishSPIPersistenceContentVersionInfo $versionInfo* @param eZPublishSPIPersistenceContentField $field*/abstract public function getFieldData( VersionInfo $versionInfo, Field $field );/*** Deletes field data for all $fieldIds in the version identified by* $versionInfo.** @param eZPublishSPIPersistenceContentVersionInfo $versionInfo* @param array $fieldIds*/abstract public function deleteFieldData( VersionInfo $versionInfo, array $fieldIds );} 13-4-26Presenter: Łukasz Serwatka Slide 26Extending eZ Publish 5§External storage
    • /*** Deletes field data for all $fieldIds in the version identified by* $versionInfo.** @param eZPublishSPIPersistenceContentVersionInfo $versionInfo* @param array $fieldIds*/public function deleteFieldData( VersionInfo $versionInfo, array $fieldIds ){$connection = $this->getConnection();$query = $connection->createDeleteQuery();$query->deleteFrom( … )->where(…)$query->prepare()->execute();}13-4-26Presenter: Łukasz Serwatka Slide 27Extending eZ Publish 5§External storage
    • §Possible to run some PHP code inside a sandbox throughthe runCallback() method<?php// Declare use statements for the classes you may needuse eZINI; // Inside a controller extending eZBundleEzPublishCoreBundleController$settingName = MySetting;$test = array( oneValue, anotherValue );$myLegacySetting = $this->getLegacyKernel()->runCallback(    function () use ( $settingName, $test )    {        // Here you can reuse $settingName and $test variables inside the legacycontext        $ini = eZINI::instance( someconfig.ini );        return $ini->variable( SomeSection, $settingName );    });13-4-26Presenter: Łukasz Serwatka Slide 28Extending eZ Publish 5§Running legacy code
    • §Stored in the Resources/translations/ directory of the bundle.§Each translation file must be named according to the following path:domain.locale.loader. For example Resources/translations/messages.fr.yml§Keyword messages preferred over messages that are written in thelanguage of the default locale. For example $t = $translator->trans(’ez5.great);§YAML is recommended configuration type§Possible to dump messages into the file with ezpublish/console$ php ezpublish/console translation:update --output-format=yml --dump-messages <locale> <bundle name>13-4-26Presenter: Łukasz Serwatka Slide 29Extending eZ Publish 5§Translations
    • §Commands should be placed under Command/ folder inside your Bundleand file name must be suffixed with Command.php, e.gEzTestCommand.phpClass EzTestCommand extends ContainerAwareCommand{protected function configure(){}protected function execute(InputInterface $input, OutputInterface$output){}}13-4-26Presenter: Łukasz Serwatka Slide 30Extending eZ Publish 5§Console commands
    • §Console command configurationClass EzTestCommand extends ContainerAwareCommand{protected function configure(){$this->setName(demo:eztest)->setDescription(’eZ Publish 5 Console Test)->addArgument(’first, InputArgument::OPTIONAL, ’Firstargument)->addOption(’second, null, InputOption::VALUE_NONE, ‘Optionparam);}}13-4-26Presenter: Łukasz Serwatka Slide 31Extending eZ Publish 5§Console commands
    • §Console command configurationClass EzTestCommand extends ContainerAwareCommand{protected function execute(InputInterface $input, OutputInterface $output){$name = $input->getArgument(’first);if ($name) {$text = Hello .$name;}if ($input->getOption(’second)) {$text = strtoupper($text);}$output->writeln($text);}}13-4-26Presenter: Łukasz Serwatka Slide 32Extending eZ Publish 5§Console commands
    • §We recommend using composer (http://getcomposer.org) for bundlesinstallation§Provide packages via https://packagist.org website for ease of distribution§Configuration with composer.json13-4-26Presenter: Łukasz Serwatka Slide 33Extending eZ Publish 5§Composer
    • {"name": ”ez/testbundle","description": “","license": "GPL-2.0","authors": [{"name": ”eZ","homepage": "http://ez.no"}],"require": {"ezsystems/ezpublish-kernel": "dev-master"},"minimum-stability": "dev","autoload": {"psr-0": {”eZTestBundle": ""}},"target-dir": ”eZ/TestBundle"}13-4-26Presenter: Łukasz Serwatka Slide 34Extending eZ Publish 5§composer.json