Skip to content

Bundles

Dealing with bundles

eZ Platform is based on the Symfony2 framework and applies a similar way of organizing the app. Like in Symfony, where "everything is a bundle", your eZ Platform application is going to be a collection of bundles.

What is a bundle?

A bundle in Symfony (and eZ Platform) is a separate part of your application that implements a feature. You can create bundles yourself or make use of available open-source bundles. You can also reuse the bundles you create in other projects or share them with the community.

Many eZ Platform functionalities are provided through separate bundles included in the installation. You can see the bundles that are automatically installed with eZ Platform in composer.json.

How to use bundles?

All the bundles containing built-in eZ Platform functionalities are installed automatically. By default, a clean eZ Platform installation also contains an AppBundle where you can place your custom code.

You can see a list of other available community-developed bundles on https://ezplatform.com/Bundles. Refer to their respective pages for instructions on how to install them.

How to create bundles?

You can generate a new bundle using a generate:bundle command. See Symfony documentation on generating bundles.

How to remove bundles?

To remove a bundle (either one you created yourself, or an out-of-the-box one that you do not need) see the How to Remove a Bundle instruction in Symfony doc.

Structuring a bundle

The AppBundle

Most projects can use the provided AppBundle, in the src folder. It is enabled by default. The project's PHP code (controllers, event listeners, etc.) can be placed there.

Reusable libraries should be packaged so that they can easily be managed using Composer.

Templates

Project templates should go into app/Resources/views.

They can then be referenced in code without any prefix, for example app/Resources/views/content/full.html.twig can be referenced in Twig templates or PHP as content/full.html.twig.

Assets

Project assets should go into the web folder.

They can be referenced as relative to the root, for example web/js/script.js can be referenced as js/script.js from templates.

All project assets are accessible through the web/assets path.

Configuration

Configuration may go into app/config. However, service definitions from AppBundle should go into src/AppBundle/Resources/config.

Importing configuration from a bundle

Tip

The following procedure is valid for any type of settings supported by Symfony framework.

If you are keeping some of your code in a bundle, dealing with core bundle semantic configuration can be tedious if you maintain it in the main app/config/ezplatform.yml configuration file.

You can import configuration from a bundle in two ways: the manual way and the implicit way.

Importing configuration manually

Out of the two ways possible, importing configuration manually is the simplest and has the advantage of being explicit. It relies on using the imports statement in your main ezplatform.yml:

1
2
3
4
5
6
imports:
    # Import the template selection rules that reside in your custom AcmeExampleBundle.
    - {resource: "@AcmeExampleBundle/Resources/config/templates_rules.yml"}
 
ezpublish:
    # ...

The templates_rules.yml should then be placed in Resources/config in AcmeExampleBundle. The configuration tree from this file will be merged with the main one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
ezpublish:
    system:
        <siteaccess>:
            content_view:
                full:
                    article:
                        template: AcmeExampleBundle:full:article.html.twig
                        match:
                            Identifier\ContentType: [article]
                    special:
                        template: '::special.html.twig'
                        match:
                            Id\Content: 142

Caution

If both cover the same settings, the imported configuration overrides the main configuration files.

Tip

If you want to import configuration for development use only, you can do so in ezplatform_dev.yml 

Importing configuration implicitly

The following example shows how to implicitly load settings on the example of eZ Platform kernel. Note that this is also valid for any bundle.

This assumes you are familiar with service container extensions.

Note

Configuration loaded this way will be overridden by the main ezplatform.yml file.

In Acme/ExampleBundle/DependencyInjection/AcmeExampleExtension:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php

namespace Acme\ExampleBundle\DependencyInjection;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Config\Resource\FileResource;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
use Symfony\Component\HttpKernel\DependencyInjection\Extension;
use Symfony\Component\DependencyInjection\Loader;
use Symfony\Component\Yaml\Yaml;

/**
 * This is the class that loads and manages your bundle configuration
 *
 * To learn more see {@link http://symfony.com/doc/current/cookbook/bundles/extension.html}
 */
class AcmeExampleExtension extends Extension implements PrependExtensionInterface
{
    // ...

    /**
     * Allow an extension to prepend the extension configurations.
     * Here we will load our template selection rules.

     *
     * @param ContainerBuilder $container
     */
    public function prepend( ContainerBuilder $container )
    {
        // Loading your YAML file containing template rules
        $configFile = __DIR__ . '/../Resources/config/template_rules.yml';
        $config = Yaml::parse( file_get_contents( $configFile ) );
        // Explicitly prepend loaded configuration for "ezpublish" namespace.
        // It will be placed under the "ezpublish" configuration key, like in ezplatform.yml.
        $container->prependExtensionConfig( 'ezpublish', $config );
        $container->addResource( new FileResource( $configFile ) );
    }
}

In AcmeExampleBundle/Resources/config/template_rules.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# You explicitly prepended config for "ezpublish" namespace in the service container extension, 
# so no need to repeat it here
system:
    <siteaccess>:
        content_view:
            full:
                article:
                    template: AcmeExampleBundle:full:article.html.twig
                    match:
                        Identifier\ContentType: [article]
                special:
                    template: '::special.html.twig'
                    match:
                        Id\Content: 142

Performance

Service container extensions are called only when the container is being compiled, so performance will not be affected.

Project example

You can see an example of organizing a simple project in the companion repository for the eZ Enterprise Beginner tutorial

Versioning a project

The recommended method is to version the whole ezplatform repository. Per installation configuration should use parameters.yml.

Built-in bundles

The following tables give an overview of the main eZ Platform bundles.

Core bundles

Bundle Description
ezpublish-kernel contains the core of the whole eZ Platform application e.g. EzPublishCoreBundle
repository-forms provides form-based interaction for the Repository Value objects
ezplatform-solr-search-engine Solr-powered search handler for eZ Platform
ez-support-tools provides functionality for system information
ezplatform-design-engine design fallback system for eZ Platform similar to legacy design fallback system
BehatBundle common reusable sentence implementations and other common needs for Behat testing in eZ bundles/projects

Enterprise

Bundle Description
date-based-publisher provides the date based publishing functionality for the eZ Studio product
flex-workflow implementation of a collaboration feature that lets you send content draft to any user for a review or rewriting

Optional bundles

Bundle Description
ezplatform-i18n centralized internationalization
ezplatform-demo-assets contains binary install data for ezsystems/ezplatform-demo
PlatformUIBundle provides the main editing and back-end interface for eZ Platform v1
PlatformUIAssetsBundle assets for PlatformUIBundle, branches will only contain meta files and config, tags will contain the assets for eZ Platform v1
ezplatform-automated-translation adds automated translation
EzSystemsPrivacyCookieBundle adds privacy cookie banner
ezplatform-richtext Field Type for supporting rich formatted text stored in a structured XML format
CommentsBundle comment bundle for eZ Platform integrating with Disqus and Facebook and allowing custom integrations
EzSystemsRecommendationBundle integration of YooChoose, a content recommendation solution
EzSystemsShareButtonsBundle adds social share buttons
RepositoryProfilerBundle profiles Platform API/SPI and sets up scenarios to be able to continuously test to keep track of performance regressions of repository and underlying storage engines
QueryBuilderBundle provides a PHP API dedicated to fluently writing repository queries

Enterprise

Bundle Description
ezstudio-cron eZ Platform EE 1.x series only - exposes cron/cron package for use in eZ Platform (or just plain Symfony) via a simple command ezpublish:cron:run
cloud-deployment-manager dedicated cloud deployment manager
StudioUIBundle contains the Studio editing interface in eZ Platform v1
ezstudio-form-builder Form Builder Bundle is a part of eZ Studio and is installed with eZ Studio meta repository in eZ Platform v1
EzLandingPageFieldTypeBundle Landing Page that is at the heart of StudioUI
ezstudio-demo-bundle represents a demo front-end website with eZ Studio
ezstudio-personalized-block eZ Systems Personalized Block Bundle

Education

Bundle Description
CookbookBundle working examples for using eZ Platform Public API
ezplatform-com the eZ Systems Developer Hub for the Open Source PHP CMS eZ Platform (example site)
ezplatform-ee-demo fork of the "ezplatform-ee" meta repository, contains changes to composer.json, AppKernel.php and config necessary to enable eZ Platform Enterprise Edition Demo. Not recommended for a clean install for new projects, but great for observation and learning (example site)
ezplatform-demo fork of "ezplatform" meta repository, contains code and dependencies for demo distribution of eZ Platform. Not recommended for a clean installation for new projects, but great for observation and learning(example site)
TweetFieldTypeBundle bundle that is created in the Field Type Tutorial (example field type)
ezplatform-drawio-fieldtype provides support for diagrams editing in eZ Platform via draw.io (example field type)
ezplatform-ee-beginner-tutorial resources used in the eZ Platform Enterprise Edition Beginner Tutorial
ExtendingPlatformUIConferenceBundle bundle created in the Extending PlatformUI tutorial
docker-php contains PHP docker image example

Documentation - additional resources

Repository Description
developer-documentation source for the developer documentation for eZ Platform, an open source CMS based on the Symfony Full Stack Framework in PHP. https://doc.ezplatform.com
user-documentation source for the user documentation for eZ Platform, an open source CMS based on the Symfony Full Stack Framework in PHP
ezpersonalization-documentation source for the eZ Personalization documentation for eZ Platform, an open source CMS based on the Symfony Full Stack Framework in PHP

Legacy

Bundle Description
ezplatform-xmltext-fieldtype XmlText field type for eZ Platform [Community co-maintained]
ezflow-migration-toolkit set of tools that helps migrate data from legacy eZ Flow extension to eZ Studio landing page management
ngsymfonytools-bundle integrates the legacy netgen/ngsymfonytools as a Legacy bundle
ezpublish-legacy-installer A custom Composer installer for eZ Publish legacy extensions
Read the Docs