The public API will give you an easy access to the eZ Publish content repository. This repository is the core component that manages content, locations (nodes in eZ Publish 4.x), sections, content types (Content Classes in eZ Publish 4.x), users, user groups, and roles. It also provides a new, clear interface for plugging in custom field types (datatypes in eZ Publish 4.x).
The public API is built on top of a layered architecture including a persistence API that abstracts storage. By using the public API, you are sure that your code will be forward compatible with future releases based on enhanced, scalable and high-performance storage engines. Applications based on the public API are also fully backwards compatible by using the included storage engine based on the current kernel and database model.
In order to test and use Public API code, you will need to build a custom bundle. Bundles are Symfony's extensions, and are therefore also used to extend eZ Publish. Symfony 2 provides code generation tools that will let you create your own bundle and get started in a few minutes.
In this chapter, we will show how to create a custom bundle, and implement both a command line script and a custom route with its own controller action and view. All shell commands assume that you use some linux shell, but those commands would of course also work on windows systems.
Generating a new bundle
First, change directory to your eZ Publish root.
Then use the app/console application, with the generate:bundle command to start the bundle generation wizard
Let's follow the instructions provided by the ward. Our objective is to create a bundle named
EzSystems/Bundles/CookBookBundle, located in the
The wizard will first ask about our bundle's namespace. Each bundle's namespace should feature a vendor name (in our own case:
EzSystems), optionally followed by a sub-namespace (we choose to use
Bundle in order to follow the kernel's conventions), and end with the actual bundle's name, suffixed with
You will then be asked about the Bundle's name, used to reference your bundle in your code. We can go with the default,
EzSystemsCookbookBundle. Just hit enter to accept the default.
The next question is your bundle's location. By default, the script offers to place it in the
src folder. This is perfectly acceptable unless you have a good reason to place it somewhere else. Just hit enter to accept the default.
Next, you need to choose the generated configuration's format, out of YAML, XML, PHP or annotations. We mostly use yaml in eZ Publish 5, and we will use it in this cookbook. Enter 'yml', and hit enter.
The last choice is to generate code snippets demonstrating the Symfony directory structure. If you're learning Symfony, it is a good idea to accept, as it will pre-create a controller, yaml files...
The generator will then summarize the previous choices, and ask for confirmation. Hit enter to confirm.
The wizard will generate the bundle, check autoloading, and ask about activation of your bundle. Hit enter to both questions to have your bundle automatically added to your Kernel (
ezpublish/EzPublishKernel.php) and routes from your bundle added to the existing routes (
Implementing a command line script in your bundle
cd <ezpublish installation root>/src/EzSystems/CookbookBundle
add the following class file CookbookCommand.php in the directory Command
php ezpublish/console cookbook:run 5
Creating and editing Content
The following recipes show how to create simple content. As we don't want to rely on a specific installation with predefined content types we first show how to create a content type group and a simple content type within this group. Then we will create a content object of the newly created content type. The last two recipes show how to create content containing images and xml text.
Recipe 2 - Creating a content type group
This snippet creates a content type group for a given identifier (Full code here).
If this snipped is run with the same init code from recipe 1 we will get an UnauthorizedException.
The solution is described in the next recipe.
Recipe 3 - Setting the user for authorizing actions
By default the repository assumes the anonymous user is acting. To change this the following code can be executed
If the user is identified by other mechanisms the user also can be loaded by its id via the service method
Recipe 4 - Creating a content type
With this snipped a content type with two fields of type 'ezstring' is created. (Full code here).
Recipe 5 - Creating content
In this recipe content is created under a given parent location. It is assumed that the loaded content type is the one created in recipe 4. (Full code here).
Recipe 6 - Updating Content
In this recipe the previously created content is updated with a new title and body in the same language. (Full code here)
Recipe 7 - Translating content
It is the same code as for updating (see recipe 6). The initial language should be set to the translation language.
Recipe 8 - Multiple translations at once
It is possible to to make an update in content or create content with more than one language. But there is a restriction - only one language can be assigned to the newly created version (which is displayed in the 4.x admin GUI in the translations column).
Recipe 9 - Creating Content containing an image
This recipe shows how to create an content object containing an image. (Full code here)
Recipe 10 - Create Content with XML Text
This recipe shows how to create content with xml text. As content type the folder is used where the description is filled with xml. It is also shown how to embed the previously created image in the description. The image Id is given by a command line argument.
Browsing, Finding, Viewing
Recipe 11 - Viewing Content
This recipe shows how to view fields of the content int the main language.
Other languages are accessible via the the language parameter in the method
$content->getField( $fieldDefinition->identifier, $otherlanguage)
Recipe 12 - Browsing Locations
This recipe shows how to browse a subtree starting from a given location. (Full code here)
Recipe 13 - Viewing Content Meta Data
This recipe shows how to read content meta data: Locations, UrlAliases, Relations, Versions, Contenttype, Section, Owner, RemoteId, Several Timestamps. (Full code here)
This script produces e.g the follwing output:
Recipe 14 - Performing a simple full text search
In this recipe a simple full text search is performed. (Full code here)
Recipe 15 - Performing an advanced search
In this recipe different criteria is combined using a logic 'AND' operation. The result is restricted additional (see recipe 9) to a given content type and subtree. (Full code here)
Working with locations
Recipe 16 - Adding a new location to content
This recipe shows how to add a new location to a given content object. (Full code here)
Recipe 17 - Move or Copy Subtree
This recipe shows how to move or copy a subtree to a given parent location (Full code here)
Recipe 18 - Hide/Unhide Location
This recipe shows how to hide/unhide a location. (Full code here)
Recipe 19 - Deleting locations
If a content has more than one location the method
removes the location and if exists all descendants of the location. However the content itself is untouched as it has still other locations.
If the deleted location is the last one of the content the content itself is deleted. This applies also to all descendants of the location.
Alternatively a location can also moved to the trash via the method:
Recipe 20 - Deleting Content
The result of deleting content permanently is equivalent to deleting all locations of content (see recipe 15).
It is done via the method:
Recipe 21 - Assinging section to content
On creation of content the section of the parent location's content is assigned by default to the new content. However it is possible to assign a specific section on creation by setting it in the ContentCreateStruct (recipe 5):
$contentCreateStruct->section = $sectionId
Later on sections can be assigned with the following code (Full code here):