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.
About this cookbook
The objective of this Public API cookbook is to progressively guide you through useful, everyday business logic, using the API in concrete recipes: obtaining a Location from a Content, fetching a set of Content, creating a User...
For each recipe, newly introduced elements will be explained in details, including the required API components (services, value objects...).
In addition to this cookbook, we strongly recommend that you use a full featured PHP IDE, such as Eclipse or PhpStorm. They will provide you with information on every piece of code you use, including objects and classes documentation. We have paid very careful attention to PHPDoc throughout this API, and such a tool is a very valuable help when using this API.
On top of this, generated public API documentation can be found online, in various formats:
- phpDocumentor: http://ezsystems.github.com/ezp-next/phpDocumentor/
- doxygen: http://ezsystems.github.com/ezp-next/doxygen/html/
- sami: http://ezsystems.github.com/ezp-next/sami/
Public API basics
eZ Publish API Repository
This entity is the entry point to everything you will do with the Public API.
It will allow you to create, retrieve update and delete all the eZ Publish objects, as well as content types, sections, content states... it is always obtained through the service container.
/** @var $repository \eZ\Publish\API\Repository\Repository $repository = $container->get( 'ezpublish.api.repository' );
Pay attention to the inline phpdoc block in this code stub. It tells your IDE that
$repository is an instance of
\eZ\Publish\API\Repository\Repository. If your IDE supports this feature, you will get code completion on the
$repository object. This helper is a huge time savior when it comes to learning about the eZ Publish API.
This of course implies that the service container is available in the context you are writing your code in.
In controllers, this is done by extending the Symfony
Controller class. It comes with a
get() method that calls the service container. In command line scripts, it requires that you extend the
ContainerAwareCommand base classe instead of
Controller. This class provides you with a
getContainer() method, that returns the service container.
In order to make it even easier to obtain the repository from controllers code, eZ Publish 5 controllers extend the a custom Controller class that provides a
You can and should of course do the same in your custom controllers.
One of the responsibilities of the Repository is user authentication. Every action will be executed as a user. In the context of a normal eZ Publish execution, the logged in user will of course be the current one, identified via one of the available authentication methods. This user's permissions will affect the behaviour of the Repository. The user may not be allowed to create Content, or view a particular section.
Logging in to the Repository is covered in the recipes of this cookbook.
The main entry point to the repository's features are services. The Public API breaks down access to Content, User, Content Types, etc features into various services. Those services are obtained via the Repository, using getServiceName() like methods:
Throughout this cookbook, you will be guided through the various capabilities those services how, and how you can use them to implement your projects.
While Services provide interaction with the repository, the elements (Content, Users) they provide interaction with are provided as read only Value Objects, in the
eZ\Publish\Core\Repository\Values namespace. Those objects are broken down into sub-namespaces:
ObjectState, each sub-namespace containing a set of value objects, such as
Those objects are read-only by design. They are only meant to be used in order to fetch data from the repository. They come with their own properties, such as $content->id, $location->hidden, but also with methods that will provide you with more complex objects, such as Relation::getSourceContentInfo() or Role::getPolicies(). By design, a value object will only give you access to data that is very closely related to it. More complex retrieval operations will require you to use the appropriate Service, using information from your Value Object.
Value info objects
Some complex Value Objects have an Info counterpart, like
ContentInfo, the counterpart for
Content. Those objects are specialized ones, that provide you with lower level information. For instance,
ContentInfo will provide you with currentVersionNo or remoteId, while Content will let you retrieve Fields, the ContentType, or previous Versions.
They are provided by the API, but are read only, can't be modified and sent back. Creation and modification of Repository values are done using Create structs and Update structs.
Create and update structs
In order to update or create elements in the Repository, you will use those structs. They are usually provided by the Service that manages the Value Objects you want to alter or create. For instance, the Content service has a
getContentCreateStruct() method, that returns a new
ContentCreateStruct object. Equivalent methods exist for UpdateStruct objects as well, and for most Value Objects.
Using those is also covered in this cookbook.