A quick look at the Symfony2 Bundle system
Migrating extensions to eZ Publish 5
01/08/2013Presenter: Łukasz Serwatka Slide 2
Extending eZ Publish 5
Presenter
Łukasz Serwatka
Product Management Technical...
01/08/2013Presenter: Łukasz Serwatka Slide 3
Extending eZ Publish 5
Preparation
 Drivers for migration (challenges, requi...
01/08/2013Presenter: Łukasz Serwatka Slide 4
Extending eZ Publish 5
Preparation
 Make in-depth analysis of the existing e...
01/08/2013Presenter: Łukasz Serwatka Slide 5
Extending eZ Publish 5
Preparation
 The eZ Publish 5 supported extension poi...
01/08/2013Presenter: Łukasz Serwatka Slide 6
Extending eZ Publish 5
New concepts in eZ Publish 5.x
eZ Publish 4.x eZ Publi...
01/08/2013Presenter: Łukasz Serwatka Slide 7
Extending eZ Publish 5
Naming differences between eZ Publish 4.x and 5.x
eZ P...
 eZ Publish 5 can be extended thanks to the bundle system
 A Bundle is a directory containing a set of files (PHP files,...
01/08/2013Presenter: Łukasz Serwatka Slide 9
Extending eZ Publish 5
Bundle Directory Structure
Bundle Directory Structure ...
01/08/2013Presenter: Łukasz Serwatka Slide 10
Extending eZ Publish 5
Bundle Directory Structure – Advanced
Bundle Director...
 Example eZ Publish 5 Bundle architecture
01/08/2013Presenter: Łukasz Serwatka Slide 11
Extending eZ Publish 5
Bundle Dir...
 File: eZTestBundle.php
<?php
Namespace eZTestBundle;
use SymfonyComponentHttpKernelBundleBundle;
class eZTestBundle exte...
 Before a Bundle can be used it has to be registered in the system.
 With the registerBundles() method, you have total c...
 eZ Publish 5 provides a shortcut for automatic bundle registration
php ezpublish/console generate:bundle --
namespace=eZ...
 File: eZTestBundle.php
<?php
Namespace eZTestBundle;
use SymfonyComponentHttpKernelBundleBundle;
class eZTestBundle exte...
 File: src/eZ/DemoBundle/Controller/MyController.php
<?php
namespace eZDemoBundleMyController;
use EzSystemsDemoBundleCon...
 File: view.html.twig
<h1>Hello</h1>
<p>I‟m a Twig template!</p>
 Created Twig template can be included as follows:
{% i...
 Legacy template include
// eZ Publish 5.0
{% ez_legacy_include "design:parts/menu.tpl" with
{"current_node_id": location...
 The best practice for extension migration regarding configuration is to keep a
compatible format
ezoe.ini
[EditorSetting...
// Assuming that current siteaccess is ezdemo_site
// The following code will work regardless of whether you are using the...
 Datatypes are FieldTypes in eZ Publish 5
 Extends eZPublishCoreFieldTypeFieldType class
 Uses Value objects for storin...
 A common issue when rendering legacy field type in eZ Publish 5 is the
API_CONTENT_EXCEPTION
 It occurs when the API th...
// Resources/config/storage_engines.yml
ezpublish.fieldType.ezsample.converter.class:
%ezpublish.fieldType.eznull.converte...
 Some FieldTypes require that you store data in the external data sources
 Possible through the eZPublishSPIFieldTypeFie...
 It is recommended to use gateway-based storage
 Implement a gateway infrastructure and a registry for the gateways
 Po...
abstract class Gateway extends StorageGateway
{
/**
* Stores data in the database based on the given field data
*
* @param...
/**
* Deletes field data for all $fieldIds in the version identified by
* $versionInfo.
*
* @param eZPublishSPIPersistence...
 Possible to run some PHP code inside a sandbox through
the runCallback() method
<?php
// Declare use statements for the ...
 Stored in the Resources/translations/ directory of the bundle.
 Each translation file must be named according to the fo...
 Commands should be placed under the Command/ folder inside your Bundle
and file name must be suffixed with Command.php, ...
 Console command configuration
Class EzTestCommand extends ContainerAwareCommand
{
protected function configure()
{
$this...
 Console command configuration
Class EzTestCommand extends ContainerAwareCommand
{
protected function execute(InputInterf...
 We recommend using composer (http://getcomposer.org) to install bundles
 Provide packages via https://packagist.org web...
{
"name": ”ez/testbundle",
"description": “",
"license": "GPL-2.0",
"authors": [
{
"name": ”eZ",
"homepage": "http://ez.no...
Upcoming SlideShare
Loading in …5
×

Migrating extensions to eZ Publish 5

4,488 views

Published on

Webinar eZ Sessions #6

Published in: Technology
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,488
On SlideShare
0
From Embeds
0
Number of Embeds
14
Actions
Shares
0
Downloads
26
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

Migrating extensions to eZ Publish 5

  1. 1. A quick look at the Symfony2 Bundle system Migrating extensions to eZ Publish 5
  2. 2. 01/08/2013Presenter: Łukasz Serwatka Slide 2 Extending eZ Publish 5 Presenter Łukasz Serwatka Product Management Technical Lead lukasz.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. 01/08/2013Presenter: Łukasz Serwatka Slide 3 Extending eZ Publish 5 Preparation  Drivers for migration (challenges, requirements) - It is very important to understand the drivers behind a migration effort  Inventory of current environment - Creating a detailed summary of the current extension portfolio really helps in terms of understanding the scope of a migration effort  Migration service provider - evaluate at least a couple of migration service providers if you do not have migration skills and staff in-house.  Migration effort estimate - the estimate depends on many factors such as extension size, database complexity, components, etc. Usually provided by the migration service provider.  Training requirements - Training requirements for existing development team on the new platform need to be assessed to ensure that they can support the new environment effectively and can participate in the migration process if required.
  4. 4. 01/08/2013Presenter: Łukasz Serwatka Slide 4 Extending eZ Publish 5 Preparation  Make in-depth analysis of the existing eZ Publish 4.x extension functionality and 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 5 and which ones still require the legacy kernel. Not all legacy features are available in eZ Publish 5 yet, and it is an ongoing process to fill the gaps.
  5. 5. 01/08/2013Presenter: Łukasz Serwatka Slide 5 Extending 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 Publish 5.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. 01/08/2013Presenter: Łukasz Serwatka Slide 6 Extending eZ Publish 5 New concepts in eZ Publish 5.x eZ Publish 4.x eZ Publish 5.x Module Controller, extends eZBundleEzPublishCoreBundleController Action & View Action, the method on the Controller to execute. View is a (Twig) template that displays the result of the Action. eZTemplate Twig, new template engine, new syntax fetch() Render function, HMVC concept, a function that enables embedding other controller calls Extension Bundle in eZ Publish 5 (Symfony2) CLI eZ Publish 5 ezpublish/console component for creating command line interfaces INI settings YAML, recommended configuration type in eZ Publish 5
  7. 7. 01/08/2013Presenter: Łukasz Serwatka Slide 7 Extending eZ Publish 5 Naming differences between eZ Publish 4.x and 5.x eZ 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 FieldValue Datatype FieldType Node 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 basic bundle skeleton: $ php ezpublish/console generate:bundle –namespace=eZ/TestBundle 01/08/2013Presenter: Łukasz Serwatka Slide 8 Extending eZ Publish 5
  9. 9. 01/08/2013Presenter: Łukasz Serwatka Slide 9 Extending eZ Publish 5 Bundle Directory Structure Bundle Directory Structure Description Controller/ contains the controllers of the bundle (e.g. HelloController.php); DependencyInjection/ holds certain dependency injection extension classes, which may import service configuration Resources/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 is copied or symbolically linked into the project web/ directory via the assets:install console command; Tests/ holds all tests for the bundle.
  10. 10. 01/08/2013Presenter: Łukasz Serwatka Slide 10 Extending eZ Publish 5 Bundle Directory Structure – Advanced Bundle Directory Structure Description API/ contains the value object definitions, service interfaces, etc. In short, public API interfaces provided by your bundle. Core/ holds field types implementation, persistence related classes, repository implementations, signal-slot implementations, etc. SPI/ (Service Provider Interface) holds interfaces that can contain one or several implementations around Persistence (database), IO (file system), FieldTypes (formerly DataTypes), Limitations (permissions system), etc. EventListeners/ holds event listener implementation for both eZ Publish 5 and LS Command/ contains Console commands; each file must be suffixed with Command.php
  11. 11.  Example eZ Publish 5 Bundle architecture 01/08/2013Presenter: Łukasz Serwatka Slide 11 Extending eZ Publish 5 Bundle Directory Structure
  12. 12.  File: eZTestBundle.php <?php Namespace eZTestBundle; use SymfonyComponentHttpKernelBundleBundle; class eZTestBundle extends Bundle { } 8/1/2013Presenter: Łukasz Serwatka Slide 12 Extending 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 bundles are used by eZ Publish 5 (including the core Symfony bundles). // ezpublish/EzPublishKernel.php public function registerBundles() { $bundles = array( ..., // register your bundles new eZTestBundleeZTestBundle(), ); // ... return $bundles; } 8/1/2013Presenter: <enter presenter in footnote> Slide 13 Extending eZ Publish 5 Registering Bundle
  14. 14.  eZ Publish 5 provides a shortcut for automatic bundle registration php ezpublish/console generate:bundle -- namespace=eZ/TestBundle php ezpublish/console assets:install --symlink php ezpublish/console cache:clear 8/1/2013Presenter: Łukasz Serwatka Slide 14 Extending eZ Publish 5 Registering Bundle
  15. 15.  File: eZTestBundle.php <?php Namespace eZTestBundle; use SymfonyComponentHttpKernelBundleBundle; class eZTestBundle extends Bundle { public function getParent() { return ’eZDemoBundle'; } } 8/1/2013Presenter: Łukasz Serwatka Slide 15 Extending eZ Publish 5 Bundle Override
  16. 16.  File: src/eZ/DemoBundle/Controller/MyController.php <?php namespace 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 stuff return $response; } }  Only works if the bundle refers to the controller using the standard EzSystemsDemoBundle:Demo:footer syntax in routes and templates 8/1/2013Presenter: Łukasz Serwatka Slide 16 Extending 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‟ %} 01/08/2013Presenter: Łukasz Serwatka Slide 17 Extending 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 a Content or a Location it will be converted to the corresponding eZ Publish Legacy objects. 01/08/2013Presenter: Łukasz Serwatka Slide 18 Extending eZ Publish 5 Working with legacy templates
  19. 19.  The best practice for extension migration regarding configuration is to keep a compatible format ezoe.ini [EditorSettings] # Skin for the editor, 'default' and 'o2k7' is included as standard Skin=o2k7 # Lets you control alignment of toolbar buttons [left|right] ToolbarAlign=left parameters: # Namespace is ezoe (INI file was ezoe.ini), scope is defined to ezdemo_site siteaccess ezoe.ezdemo_site.EditorSettings.Skin: o2k7 ezoe.ezdemo_site.EditorSettings.ToolbarAlign: left 01/08/2013Presenter: Łukasz Serwatka Slide 19 Extending eZ Publish 5 Working with INI settings
  20. 20. // Assuming that current siteaccess is ezdemo_site // The following code will work regardless of whether you are using the legacy extension or the migrated one. $resolver = $this->getConfigResolver(); $skin = $resolver->getParameter( ’EditorSettings.Skin', ’ezoe' ); $toolbarAlign= $resolver->getParameter( ’EditorSettings.ToolbarAlign', ’ezoe' ); 01/08/2013Presenter: Łukasz Serwatka Slide 20 Extending 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 (extends eZPublishCoreFieldTypeValue)  Requires converters for field values in legacy storage (implements eZPublishCorePersistenceLegacyContentFieldValueConverter)  A NULL Converter is available for developers’ convenience  Uses gateways for getting data from external storage (custom tables) 8/1/2013Presenter: Łukasz Serwatka Slide 21 Extending eZ Publish 5 FieldType
  22. 22.  A common issue when rendering legacy field type in eZ Publish 5 is the API_CONTENT_EXCEPTION  It occurs when the API throws an exception that could not be caught internally (missing field type, missing converter, internal error...)  For simple field types, declaration of a NULL converter is often a resolution // Resources/config/fieldtypes.yml ezpublish.fieldType.ezsample.class: %ezpublish.fieldType.eznull.class% ezpublish.fieldType.ezsample: class: %ezpublish.fieldType.ezsample.class% parent: ezpublish.fieldType arguments: [ ”ezsample" ] tags: - {name: ezpublish.fieldType, alias: ezsample} 8/1/2013Presenter: Łukasz Serwatka Slide 22 Extending eZ Publish 5 NULL Converter
  23. 23. // Resources/config/storage_engines.yml ezpublish.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'} 8/1/2013Presenter: Łukasz Serwatka Slide 23 Extending eZ Publish 5 NULL Converter
  24. 24.  Some FieldTypes require that you store data in the external data sources  Possible through the eZPublishSPIFieldTypeFieldStorage interface. // Resources/config/fieldtypes.yml parameters: ezpublish.fieldType.ezsample.externalStorage.class: eZPublishCoreFieldTypeSampleSampleStorage services: ezpublish.fieldType.ezsample.externalStorage: class: %ezpublish.fieldType.ezsample.externalStorage.class% tags: - {name: ezpublish.fieldType.externalStorageHandler, alias: ezsample} 8/1/2013Presenter: Łukasz Serwatka Slide 24 Extending 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 eZPublishCoreFieldTypeStorageGateway // Resources/config/fieldtypes.yml parameters: ezpublish.fieldType.ezsample.storage_gateway.class: eZPublishCoreFieldTypeSampleSampleStorageGatewayLegacyStorage services: ezpublish.fieldType.ezsample.storage_gateway: class: %ezpublish.fieldType.ezsample.storage_gateway.class% tags: - {name: ezpublish.fieldType.externalStorageHandler.gateway, alias: ezsample, identifier: LegacyStorage} 8/1/2013Presenter: Łukasz Serwatka Slide 25 Extending 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 ); } 8/1/2013Presenter: Łukasz Serwatka Slide 26 Extending 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(); } 8/1/2013Presenter: Łukasz Serwatka Slide 27 Extending eZ Publish 5 External storage
  28. 28.  Possible to run some PHP code inside a sandbox through the runCallback() method <?php // Declare use statements for the classes you may need use 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 legacy context $ini = eZINI::instance( 'someconfig.ini' ); return $ini->variable( 'SomeSection', $settingName ); } ); 8/1/2013Presenter: Łukasz Serwatka Slide 28 Extending 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 the language of the default locale. For example $t = $translator->trans(’ez5.great');  YAML is the recommended configuration type  Possible to dump messages into a file with ezpublish/console $ php ezpublish/console translation:update --output- format=yml --dump-messages <locale> <bundle name> 8/1/2013Presenter: Łukasz Serwatka Slide 29 Extending eZ Publish 5 Translations
  30. 30.  Commands should be placed under the Command/ folder inside your Bundle and file name must be suffixed with Command.php, e.g EzTestCommand.php Class EzTestCommand extends ContainerAwareCommand { protected function configure() { } protected function execute(InputInterface $input, OutputInterface $output) { } } 8/1/2013Presenter: Łukasz Serwatka Slide 30 Extending eZ Publish 5 Console commands
  31. 31.  Console command configuration Class EzTestCommand extends ContainerAwareCommand { protected function configure() { $this ->setName('demo:eztest') ->setDescription(’eZ Publish 5 Console Test') ->addArgument(’first', InputArgument::OPTIONAL, ’First argument') ->addOption(’second', null, InputOption::VALUE_NONE, ‘Option param') ; } } 8/1/2013Presenter: Łukasz Serwatka Slide 31 Extending eZ Publish 5 Console commands
  32. 32.  Console command configuration Class 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); } } 8/1/2013Presenter: Łukasz Serwatka Slide 32 Extending eZ Publish 5 Console commands
  33. 33.  We recommend using composer (http://getcomposer.org) to install bundles  Provide packages via https://packagist.org website for ease of distribution  Configuration with composer.json 8/1/2013Presenter: Łukasz Serwatka Slide 33 Extending 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" } 8/1/2013Presenter: Łukasz Serwatka Slide 34 Extending eZ Publish 5 composer.json

×