Migrating eZ Publish 4 extensions to eZ Publish 5
2013-04-23Presenter: Łukasz Serwatka Slide 2Extending eZ Publish 5§PresenterŁukasz SerwatkaProduct Management Technical Le...
13-4-26Presenter: Łukasz Serwatka Slide 3Extending eZ Publish 5§Preparation§Drivers for migration (challenges, requirement...
13-4-26Presenter: Łukasz Serwatka Slide 4Extending eZ Publish 5§Preparation§Make in-depth analysis of the existing eZ Publ...
13-4-26Presenter: Łukasz Serwatka Slide 5Extending eZ Publish 5§Preparation§The eZ Publish 5 supported extension points at...
13-4-26Presenter: Łukasz Serwatka Slide 6Extending eZ Publish 5§New concepts in eZ Publish 5.xeZ Publish 4.x eZ Publish 5....
13-4-26Presenter: Łukasz Serwatka Slide 7Extending eZ Publish 5§Naming differences between eZ Publish 4.x and 5.xeZ Publis...
§eZ Publish 5 can be extended thanks to the bundle system§A Bundle is a directory containing a set of files (PHP files, st...
13-4-26Presenter: Łukasz Serwatka Slide 9Extending eZ Publish 5§Bundle Directory StructureBundle Directory Structure Descr...
13-4-26Presenter: Łukasz Serwatka Slide 10Extending eZ Publish 5§Bundle Directory Structure – AdvancedBundle Directory Str...
§Example eZ Publish 5 Bundle architecture13-4-26Presenter: Łukasz Serwatka Slide 11Extending eZ Publish 5§Bundle Directory...
§File: eZTestBundle.php<?phpNamespace eZTestBundle;use SymfonyComponentHttpKernelBundleBundle;class eZTestBundle extends B...
§Before a Bundle can be used it has to be registered in the system.§With the registerBundles() method, you have total cont...
§eZ Publish 5 provides a shortcut for automatic bundle registrationphp ezpublish/console generate:bundle--namespace=eZ/Tes...
§File: eZTestBundle.php<?phpNamespace eZTestBundle;use SymfonyComponentHttpKernelBundleBundle;class eZTestBundle extends B...
§File: src/eZ/DemoBundle/Controller/MyController.php<?phpnamespace eZDemoBundleMyController;use EzSystemsDemoBundleControl...
§File: view.html.twig<h1>Hello</h1><p>I’m a Twig template!</p>§Created Twig template can be included as follows:{% include...
§Legacy template include// eZ Publish 5.0{% ez_legacy_include "design:parts/menu.tpl" with{"current_node_id": location.con...
§The best practice for extension migration regarding configuration is to keep acompatible formatezoe.ini[EditorSettings]# ...
// Assuming that the current siteaccess is ezdemo_site// The following code will work whether youre using the legacy exten...
§Datatypes are FieldTypes in eZ Publish 5§Extends eZPublishCoreFieldTypeFieldType class§Uses Value objects for storing arb...
§A common issue with rendering legacy field types in eZ Publish 5 is theAPI_CONTENT_EXCEPTION§It occurs when the API throw...
// Resources/config/storage_engines.ymlezpublish.fieldType.ezsample.converter.class:%ezpublish.fieldType.eznull.converter....
§Some FieldTypes store data in external data sources§Possible through the eZPublishSPIFieldTypeFieldStorage interface.// R...
§It is recommended to use gateway-based storage§Implement a gateway infrastructure and a registry for the gateways§Possibl...
abstract class Gateway extends StorageGateway{/*** Stores data in the database based on the given field data** @param eZPu...
/*** Deletes field data for all $fieldIds in the version identified by* $versionInfo.** @param eZPublishSPIPersistenceCont...
§Possible to run some PHP code inside a sandbox throughthe runCallback() method<?php// Declare use statements for the clas...
§Stored in the Resources/translations/ directory of the bundle.§Each translation file must be named according to the follo...
§Commands should be placed under Command/ folder inside your Bundleand file name must be suffixed with Command.php, e.gEzT...
§Console command configurationClass EzTestCommand extends ContainerAwareCommand{protected function configure(){$this->setN...
§Console command configurationClass EzTestCommand extends ContainerAwareCommand{protected function execute(InputInterface ...
§We recommend using composer (http://getcomposer.org) for bundlesinstallation§Provide packages via https://packagist.org w...
{"name": ”ez/testbundle","description": “","license": "GPL-2.0","authors": [{"name": ”eZ","homepage": "http://ez.no"}],"re...
Upcoming SlideShare
Loading in …5
×

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

2,885 views

Published on

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

Published in: Technology

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

  1. 1. Migrating eZ Publish 4 extensions to eZ Publish 5
  2. 2. 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)
  3. 3. 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.
  4. 4. 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.
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. §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
  9. 9. 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.
  10. 10. 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
  11. 11. §Example eZ Publish 5 Bundle architecture13-4-26Presenter: Łukasz Serwatka Slide 11Extending eZ Publish 5§Bundle Directory Structure
  12. 12. §File: eZTestBundle.php<?phpNamespace eZTestBundle;use SymfonyComponentHttpKernelBundleBundle;class eZTestBundle extends Bundle{}13-4-26Presenter: Łukasz Serwatka Slide 12Extending eZ Publish 5§Main Bundle Class
  13. 13. §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
  14. 14. §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
  15. 15. §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
  16. 16. §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
  17. 17. §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
  18. 18. §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
  19. 19. §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
  20. 20. // 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
  21. 21. §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
  22. 22. §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
  23. 23. // 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
  24. 24. §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
  25. 25. §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
  26. 26. 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
  27. 27. /*** 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
  28. 28. §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
  29. 29. §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
  30. 30. §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
  31. 31. §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
  32. 32. §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
  33. 33. §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
  34. 34. {"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

×