Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
   eZ Publish 4.x / legacy

eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

We will start by going through the various ways to find and retrieve content from eZ Publish using the API. While this will be covered in further dedicated documentation, it is necessary to explain a few basic concepts of the Public API. In the following recipes, you will learn about the general principles of the API as they are introduced in individual recipes.

Displaying values from a Content

In this recipe, we will see how to fetch a Content instance from the repository, and obtain its Field's content. 

Let's first see the full code. You can see the Command line version at

Viewing content

Let's analyze this code block by block.

This is the initialization part. As explained above, everything in the Public API goes through the repository via dedicated services. We get the repository from the service container, using the method get() of our container, obtained via $this->getContainer(). Using our $repository variable, we fetch the two services we will need using getContentService() and getFieldTypeService().

Everything starting from line 5 is about getting our Content, and iterating over its Fields. You can see that the whole logic is part of a try/catch block. Since the Public API uses Exceptions for error handling, this is strongly encouraged, as it will allow you to conditionally catch the various errors that may happen. We will cover the exceptions we expect in a next paragraph.

The first thing we do is use the Content Service to load a Content using its ID, 66: $contentService->loadContent( 66 ). As you can see on the API doc page, this method expects a Content ID, and returns a Content Value Object.

This block is the one that actually displays the value.

It iterates over the Content's (Content Object) fields using the ContentType's (Content Class) FieldDefinitions (Content Class Attribute) ($content->contentType->fieldDefinitions).

For each Field Definition (Content Class Attribute), we start by displaying its identifier ($fieldDefinition->identifier). We then get the FieldType (Datatype) instance using the FieldType Service ($fieldTypeService->getFieldType( $fieldDefinition->fieldTypeIdentifier )). This method expects the requested FieldType's identifier, as a string (ezstring, ezxmltext...), and returns an eZ\Publish\API\Repository\FieldType object.

The Field object (Content Object Attribute) is obtained using the getField() method of the Content Value Object we obtained using ContentService::loadContent().

Using this FieldType object, we can convert the Field's value to a hash using the toHash() method, provided by every FieldType. This method returns a native type (string, hash) out of a Field instance.

With this example, you should get a first idea on how you interact with the API. Everything is done through services, each service being responsible for a specific part of the repository (Content, FieldType, etc).

Loading Content in different languages

Since we didn't specify any language code, our Field objects is returned in the default language, depending on your language settings in ezpublish.yml. If you want to use a non-default language, you can specify a language code in the getField() call:

Exceptions handling

As said earlier, the Public API uses Exceptions to handle errors. Each method of the API may throw different exceptions, depending on what it does. Which exceptions can be thrown is usually documented for each method. In our case, loadContent() may throw two type of exceptions: NotFoundException if the requested ID wasn't found, and UnauthorizedException if the currently logged in user isn't allowed to view the requested content.

It is a good practice to cover each exception you expect to happen. In this case, since our Command takes the content ID as a parameter, this ID may either not exist, or the referenced content may not be visible to our user. Both cases are covered with explicit error messages.

Traversing a Location subtree

This recipe will show how to traverse a Location's subtree. The full code implements a command that takes a Location ID as an argument, and recursively prints this location's subtree.

In this code, we introduce the LocationService. This service is used to interact with locations (eZ Publish 4 nodes). We use two methods from this service: loadLocation(), and loadLocationChildren().

Loading a location

As for the ContentService, loadLocation() returns a  Value Object, here a Location. Errors are handled with exceptions: NotFoundException if the Location ID couldn't be found, and UnauthorizedException if the current repository user isn't allowed to view this location.

Iterating over a Location's children

LocationService::loadLocationChildren() returns an array of Location Value Objects that we can iterate over.

Note that unlike loadLocation(), we don't need to care for permissions here: the currently logged in user's permissions will be respected when loading children, and locations that can't be viewed won't be returned at all.

Full code

Should you need more advanced children fetching methods, the SearchService is what you are looking for.

Viewing Content Meta Data

Content is a central piece in the Public API. You will often need to start from a Content, and dig in from its metadata. Content metadata is made available through ContentInfo objects. This Value Object mostly provides primitive metadata: contentTypeId, publishedDate or mainLocationId.

The full example implements an ezpublish:cookbook:view_content_metadata command that prints out all the available metadata given a content ID.

We introduce here several new services: URLAliasService, UserService and SectionService. The concept should be familiar to you now.

Setting the repository user

In a command line script, the repository runs as if executed by the anonymous user. In order to identify as a different user, you need to use the UserService as follows:

This may be crucial when writing maintenance or synchronization scripts.

This is of course not required in template functions or controller code, as the HTTP layer will take care of identifying the user, and automatically set it in the repository.

The code will load a ContentInfo object using the provided ID, and use 

Performing a simple full text search

In this recipe a simple full text search is performed. (Full code here)

a simple full text search

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)

  • No labels