Introduction
Locations
A Content item could not function in the system without having a place = =E2=80=93 a Location =E2=80=93 assigned to it. When a new Content item= is published, a new Location is automatically created and the item is plac= ed in it.
Together, all Locations form a tree which is the basic way of organizing= Content in the system and specific to eZ products. Every published Content= item has a Location and, as a consequence, also a place in this tree.
A Content item receives a Location only once it has been published.= This means that a freshly created draft does not have a Location yet.
A Content item can have more than one Location. This can be used to have= the same content in two or more places in the tree, for example an article= at the same time on the front page and in the archive. Even in such a case= , one of these places is always the Main Location.
The tree is hierarchical, with an empty root Location (which is not assi= gned any Content item) and a structure of dependent Locations below it. Eve= ry Location (aside from the root) has one parent Location and can have any = number of children. There are no Locations outside this tree.
Top level Locations
Top level Locations are direct children of the root of the tree. The roo= t has ID Location 1, is not related to any Content items and should not be = used directly.
Under this root there are preset top level Locations in each installatio= n which cannot be deleted:
![](=3D"/download/attachments/31432023/content_structure_media_library.png?vers=)
Content
"Content" is the top level Location for the actual contents of a site. T= his part of the tree is typically used for organizing folders, articles, in= formation pages, etc. This means that it contains the actual content struct= ure of the site, which can be viewed by selecting the "Content structure" t= ab in the Content mode interface. The default ID number of the "Content" Lo= cation is 2; it references a "Folder" Content item.
Media
"Media" is the top level Location which stores and organizes information= that is frequently used by Content items located below the "Content" node.= It usually contains images, animations, documents and other files. They ca= n be viewed by selecting the "Media library" tab in the Content mode interf= ace. The default ID number of the "Media" Location is 43; it references a "= Folder" Content item.
Users
![](=3D"/download/attachments/31432023/admin_panel_users.png?version=3D1&mo=)
"Users" is the top level Location that contains the built-in system for = managing user accounts. A user is simply a Content item of the "User accoun= t" Content Type. The users are organized within "User group" Content items = below this Location. In other words, the "Users" Location contains the actu= al users and user groups, which can be viewed by selecting the "Users" tab = in the Admin Panel. The default identification number of the "Users" Locati= on is 5; it references a "User group" Content item.
Other top level Locations
Another top level location, with the ID 48, corresponds to "Setup" and i= s not regularly used to store content.
You should not add any more content directly below Location 1, but inste= ad store any content under one of those top-level Locations.
Location visibility
Location visibility is a mechanism which allows you to control which par= ts of the content tree are available to the visitor.
Given that once a Content item is published, it cannot be un-published, = limiting visibility is the only method used to withdraw content from the we= bsite without moving it to Trash. When the Location of a Content item is hi= dden, any access to it will be denied, preventing the system from displayin= g it.
Visibility needs not be set individually for every Location. Instead, wh= en a Location is hidden, all of its descendants in the tree will be hidden = as well. This means that a Location can have one of three different visibil= ity statuses:
-
Visible
-
Hidden
-
Hidden by superior
By default all Locations are Visible. If a Location is made invisible ma= nually, its status is set to Hidden. At the same time all Locations under i= t will change status to Hidden by superior.
From the visitor's perspective a Location behaves the same whether its s= tatus is Hidden or Hidden by superior =E2=80=93 it will be unavailable in t= he website. The difference is that a Location Hidden by superior cannot be = revealed manually. It will only become visible once all of its ancestor Loc= ations are made Visible again.
A Hidden by superior status does not override a Hidden status. This mean= s that if a Location is Hidden manually and later one of its ancestors is H= idden as well, the first Location's status does not change =E2=80=93 it rem= ains Hidden (not Hidden by superior). If the ancestor Location is made visi= ble again, the first Location still remains Hidden.
The way visibility works can be illustrated using the following scenario= s:
Hiding a visible Location
When you hide a Location that was visible before, it will get the status= Hidden. Underlying Locations will be marked Hidden by superior. The visibi= lity status of underlying Locations that were already Hidden or Hidden by s= uperior will not be changed.
Hiding a Locat= ion which is Hidden by superior
When you explicitly hide a Location which was Hidden by superior, it wil= l get the status Hidden. Since the underlying Locations are already either = Hidden or Hidden by superior, their visibility status will not be changed.<= /p>
Revealing a Lo= cation with a visible ancestor
=
When you reveal a Location which has a visible ancestor, this Location a= nd its children will become visible. However, underlying Locations that wer= e explicitly hidden by a user will retain the Hidden status (and their chil= dren will be remain Hidden by superior).
Revealing a Loc= ation with a Hidden ancestor
=
When you reveal a Location that has a Hidden ancestor, it will n= ot become Visible itself. Because it still has invisible ancestors= , its status will change to Hidden by superior.
Visibility mechanics
The visibility mechanics are controlled by two flags: Hidden flag and In= visible flag. The Hidden flag informs whether the node has been hidden by a= user or not. A raised Invisible flag means that the node is invisible eith= er because it was hidden by a user or by the system. Together, the flags re= present the three visibility statuses:
| Hidden flag | Invisible flag | Status |
|---|---|---|
| - | - | The Location is visible. |
| 1 | 1 | The Location is invisible and it was hidden by a= user. |
| - | 1 | The Location is invisible and it was hidden by t= he system because its ancestor is hidden/invisible. |
Content Relations
Content items are located in a tree structure through the Locations they= are placed in. However, Content items themselves can also be related to on= e another.
A Relation can be created between any two Content items in the repositor= y. This feature is typically used in situations when you need to connect an= d/or reuse information that is scattered around in the system. For example,= it allows you to add images to news articles. Instead of using a fixed set= of image attributes, the images are stored as separate Content items outsi= de the article.
There are different types of Relations available in the system. First of= all, content can be related on item or on Field level.
Relations at Field level are created using one of two special Field Type= s: Content relation (single) and Content relations (multiple). As the names= suggest, such Fields allow you to select one or more other Content items i= n the Field value, which will be linked to these Fields. Content relation (= single) is an example of a one-to-one relationship, and Content relations (= multiple) =E2=80=93 a one-to-many relationship.
Relations at item level can be of three different types:
- Common relations are created between two Content items using the Public= API.
- RichText linked relations are created using a Field of the RichText typ= e. Whenever an internal link (a link to another Location or Content item) i= s inserted into a Field represented by this Field Type, the system will aut= omatically create a relation of this type. Note that such a relation is aut= omatically removed from the system when the corresponding link is removed f= rom the Content item.
- RichText embedded relations also use a RichText Field. Whenever an Embe= d element is inserted into a Field represented by this Field Type, the syst= em will automatically create a relation of this type, that is relate the em= bedded Content item to the one that is being edited. Note that a relation o= f this type is automatically removed from the system when the corresponding= element is removed.
Sections
Sections are used to divide Content items in the tree into groups that a= re more easily manageable by content editors. Division into Sections allows= you, among others, to set permissions for only a part of the tree.
Technically, a Section is simply a triplet: a number, a name and an iden= tifier. Content items are placed in Sections by being assigned the Section = ID, with one item able to be in only one Section.
When a new Content item is created, its Section ID is set to the default= Section (which is usually Standard). When the item is published it is assi= gned to the same Section as its parent. Because Content must always be in a= Section, unassigning happens by choosing a different Section to move it in= to . If a Content item has multiple Location assignments then it is always = the Section ID of the item referenced by the parent of the main Location th= at will be used. In addition, if the main Location of a Content item with m= ultiple Location assignments is changed then the Section ID of that item wi= ll be updated.
Sections can only be removed if no Content items are assigned to them. E= ven then, it should be done carefully. When a Section is deleted, it is onl= y its definition itself that will be removed. Other references to the Secti= on will remain and thus the system will most likely be in an inconsistent s= tate.That is why removing Sections may corrupt permission settings, templat= e output and other things in the system.
Section ID numbers are not recycled. If a Section is removed, its ID num= ber will not be reused when a new Section is created.
Permissions
Permissions in Platform form one of the most advanced permissions system= s around, allowing you to define very fine-grained rights for your Editors,= Visitors, Members and other users.
Overview
In the permission system a User by default does not have access to anyth= ing. To get access they need to inherit Roles, typically assigned to the Us= er Group they belong to.
Model
Roles
First part of the permission model is the Roles, and they consist of the= following parts:
RoleLimitation *- RoleAssignment >- Role -< Policy -*< Limita= tion
- A Role assignment can optionally have a Limitation, Role Limitation examples: SubTreeLimitation or SectionLimitation
- A Role can have several assignments, Role example: Editor, Member, ProSubscriber
- A Role consists of several Policies, Policy example: content/read/*, content/edit/* (where * refers to fu= ll access, that is no Limitation)
- A Policy optionally consists of several Limitations, Limitation example:ContentTypeLimitation,SectionLimitation,OwnerLimitation
See Role Policies Map for further informations.
<=
/p>
Users
Second part of the model is made up of Users and User Groups:
User -*< UserGroup
- A User can be member of several User Groups, User Group examples: Administrator Users, Member Users, ProS= ubscriber Users
Role assignments
Last part on the permission model is the fact that Role assignments can = be assigned to both Users and User Groups:
User - RoleAssignment - UserGroup
Best Practice
Best practice is to avoid assigning Roles to Users directly, and instead= to make sure you model your content (types, structure, sections, etc.)= in a way that can be reflected in generic roles. Besides being much e= asier to manage and keep on top of security-wise, this also makes sure your= system performs best. The more Role assignments and complex Policies y= ou add for a given User, the more complex the search/load queries powering = the whole CMS will be, as they always take permissions into account.
Persistence Cache
Layers
Persistence cache can best be described as an implementation of SP=
I\Persistence that decorates the main backend implementation
As shown in the illustration, this is done in the exact same way as the = SignalSlot feature is a custom implementation of API\Repository decorating&= nbsp;the main Repository. In the case of Persistence Cache, instead of send= ing events on calls passed on to the decorated implementation, most of the = load calls are cached, and calls that perform changes purge the affected ca= ches. This is done using a Cache service which is provided by StashBundle; = this Service wraps around the Stash library to provide Symfony logging / de= bugging functionality, and allows cache handlers (Memcached, Redis, Fil= esystem, etc.) to be configured using Symfony configuration. For how t= o reuse this Cache service in your own custom code, see below.
Transparent cache
With the persistence cache, just like with the HTTP cache, eZ Platform t= ries to follow principles of "Transparent caching", this can shortly be des= cribed as a cache which is invisible to the end user and to the admin/edito= rs of eZ Platform where content is always returned "fresh". In other words,= there should be no need to manually clear the cache like it was frequently= the case with eZ Publish 4.x. This is possible thanks to an interface that= follows CRUD (Create Read Update Delete) operations per domain, a= nd the fact that the number of other operations capable of affecting a cert= ain domain is kept to a minimum.
Entity stored only once
To make the transparent caching principle as effective as possible, enti=
ties are, as much as possible, only stored once in cache by their primary i=
d. Lookup by a lternative identifiers (identifier,=
remoteId, etc.) is only cached with the identifier as cache k=
ey and primary id as its cache value, and compo=
sitions (list of objects) usually keep only the arra=
y of primary id's as their cache value.
This means a couple of things:
- Memory consumption is kept low
- Cache purging logic is kept simple (For example:
$sectionService-= >delete( 3 )clears "section/3" cache entry) - Lookup by
identifierand list of objects needs several cac= he lookups to be able to assemble the result value - Cache warmup usually takes several page loads to reach full as identifi= er is first cached, then the object
What is cached?
Persistence cache aims at caching most SPI\Persistence=
calls used in common page loads, including everything needed for permissio=
n checking and url alias lookups.
Notes:
UrlWildCardHandleris not currently cached- Currently in case of transactions this is handled very simply by cleari= ng all cache on rollback, this can be improved in the future if needed.
- Some tree/batch operations will cause clearing all persistence cache, t= his will be improved in the future when we change to a cache service cable = of cache tagging.
- Search is not defined as Persistence and the queries themselves are not= planned to be cached. Use = Solr which does this for you to improve scale and offload your dat= abase.
For further details on which calls are cached or not, and where/how = to contribute additional caches, check out the source.
Configuration
Content Repository Con= figuration
The content repository is where all your content is bee= n stored. It is the heart of eZ Platform which you interact with using Publ= ic API.
To store data, the content repository uses a storage engine that can virtually can work with any kind of storage (RDBMS, NoSQL, et= c.). eZ Publish 5 came with a relational storage engine, compatible with v4= .x: the Legacy storage engine, which is the default.
You can define several repositories within a single application. However= , you can only use one per site.
Configuration examples
Using default values
ezpublish:
repositories:
# Defining repository with alias "main"
# Default storage engine is used, with default connection
# Equals to:
# main: { engine: legacy, connection: <defaultConnectionName>=
}
main: ~
system:
# All members of my_siteaccess_group will use "main" repository
# No need to set "repository", it will take the first defined repos=
itory by default
my_siteaccess_group:
# ...=20
If no repository is specified for a siteaccess or siteaccess group, the =
first defined repository (under ezpublish.repositories) will b=
e used.
All explicit
doctrine:
dbal:
default_connection: my_connection_name
connections:
my_connection_name:
driver: pdo_mysql
host: localhost
port: 3306
dbname: my_database
user: my_user
password: my_password
charset: UTF8
another_connection_name:
# ...
ezpublish:
repositories:
first_repository: { engine: legacy, connection: my_connection_name,=
config: {} }
second_repository: { engine: legacy, connection: another_connection=
_name, config: {} }
# ...
system:
my_first_siteaccess:
repository: first_repository
# ...
my_second_siteaccess:
repository: second_repository=20
Legacy storage engine
Legacy storage engine uses Doctrine DBAL (Database Abstraction Layer). Database settings are= supplied by DoctrineBundle. As such, you can re= fer to DoctrineBundle's documentation.
ORM
Doctrine ORM is not provided by default. If you want to=
use it, you will need to add doctrine/orm as a dependency in =
your composer.json.
Field groups configuration
V1.3=
Field groups, used in content and Content Type editing, can be configure= d from the repository section. Values entered there are field group ide= ntifiers:
repositories:
default:
fields_groups:
list: [content, features, metadata]
default: content=20
These identifiers can be given human-readable values and translated. Tho=
se values will at the moment be used when editing Content Types. The transl=
ation domain is ezplatform_fields_groups.
This file wi=
ll define English names for field groups:
content: Content metadata: Metadata user_data: User data=20
Limit of archived = Content item versions
V1.7=
default_version_archive_limit controls the number of archiv=
ed versions per Content item that will be stored in the repository, by defa=
ult set to 5. This setting is configured in the following way (typically in=
ezplatform.yml):
ezpublish:
repositories:
default:
options:
default_version_archive_limit: 10=20
This limit is enforced on publishing a new version and only covers archi= ved versions, not drafts.
Persistence cache confi= guration
Tech Note
Current implementation uses a caching library called Stash (= via StashBundle). Stash supports the followi= ng cache backends: FileSystem, Memcache, APC, Sqlite, Redis&nb= sp;and BlackHole.
Use of Memcached (or, experimentally, Redis) is a requirement for us= e in Clustering setup. For an overview of this feature, see Clustering.
Cache service
The cache system is exposed as a "cache" service, and can be reused by a= ny other service as described in the Using Cache service sectio= n.
Configuration
By default, configuration currently uses FileSystem, wi=
th %kernel.cache_dir%/stash to store cache files.
The configuration is placed in app/config/config.yml and lo=
oks like this:
stash:
caches:
default:
drivers:
- FileSystem
inMemory: true
registerDoctrineAdapter: false=20
Note for "inMemory" cache with long running scripts
Use inMemory with caution, and avoid it completely for long=
running scripts for the following reasons:
- It does not have any limits, so can result in the application running o= ut of PHP memory.
- Its cache pool is by design a PHP variable and is not shared acro= ss requests/processes/servers, so data becomes stale if any other concurren= t activity happens towards the repository.
Multi repository setup
In ezplatform.yml you can specify which cache pool you want=
to use on a siteaccess or sitegroup level. The following example shows use=
in a sitegroup:
ezpublish:
system:
# "site_group" refers to the group configured in site access
site_group:
# "default" refers to the cache pool, the one configured on sta=
sh.caches above
cache_pool_name: "default"
=20
One cache pool for each repository
Stash cache backend co= nfiguration
General settings
To check which cache settings are available for your installation, run t= he following command in your terminal:
php app/console config:dump-reference stash=20
FileSystem
This cache backend uses the local filesystem, by default the Symfony cac= he folder. As this is per server, it does not support multi server (cluster) setups !
Available settings
path |
The path where the cache is placed; default is <=
code>%kernel.cache_dir%/stash, effectively app/cache/<env&g=
t;/stash |
dirSplit |
Number of times the cache key shou= ld be split up to avoid having too many files in each folder; default is 2.= |
filePermissions |
The permissions of the cache file;= default is 0660. |
dirPermissions |
The permission of the cache file d= irectories (see dirSplit); default is 0770. |
memKeyLimit |
Limit on how many key to path e= ntries are kept in memory during execution at a time to avoid having to rec= alculate the path on key lookups; default is 200. |
keyHashFunction |
Algorithm used for creating paths;=
default is md5. Use crc32 on Windows to avoid path length issues. |
Issues with Microsoft Windows
If you are using a Windows OS, you may encounter an issue regarding
Solution is to change the hash algorithm used by Stash.=
stash:
caches:
default:
drivers:
- FileSystem
inMemory: true
registerDoctrineAdapter: false
FileSystem:
keyHashFunction: 'crc32'=20
This configuration is only recommended for Windows users.
Note: You can also define the path where you wa=
nt the cache files to be generated to be able to get even shorter system pa=
th for cache files.
FileSystem cach= e backend troubleshooting
By default, Stash Filesystem cache backend stores cache to a sub-folder =
named after the environment (i.e. app/cache/dev, app/cac=
he/prod). This can lead to the following issue: if different environ=
ments are used for operations, persistence cache (manipulating content, mos=
tly) will be affected and cache can become inconsistent.
To prevent this, there are 2 solutions:
1. Manual
Always use the same environment, for web, command = line, cronjobs etc.
2 . Share stash cache across Symfony environments (prod / dev / = ..)
Either by using another Stash cache backend, or by setting Stash to use = a shared cache folder that does not depend on the environment.
In ezplatform.yml:
stash:
caches:
default:
FileSystem:
path: "%kernel.root_dir%/cache/common"
=20
This will store stash cache to app/cache/common.
APC & APCu
This cache backend is using shard memory with APC's user cache feature. = As this is per server, it does not support multi server (cluster) setups .
Not supported because of following limitation
As APC(u) user cache is not shared between processes, it is not possible=
to clear the user cache from CLI, even if you set apc.enable_cli to On. That is why publishin=
g content from a command line script won't let you properly clear SPI Persi=
stence cache.
Please also note that the default value for apc.shm_size is 128MB. However, 256MB is recommended for APC to work properly. For mo=
re details please refer to the APC configuration manual.
Available settings
ttl |
The time to live of the cache in seconds; defaul= t is 500 (8.3 minutes) |
namespace =
|
A namespace to prefix cache keys w=
ith to avoid key conflicts with other eZ Platform sites on same eZ Platform=
installation; default is null. |
Redis
EXPERIMENTAL
This cache backend is using Redis, a in-memory data structure store,= via Redis pecl extension. This is an alternative cac= he solution for multi server= (cluster) setups, besides using= Memcached.
Available settings
servers |
Array of Redis servers: <=
code> server : Host or IP of your Redis server |
password <=
/code> |
Optional setting if there is a pas= sword to connection to a given Redis server in plain text over the network.= |
| database | Optional setting to specify a give= n Redis database to use. |
Example
stash:
caches:
default:
drivers: [ Redis ]
Redis:
servers:
-
server: 'redis1.ez.no'
port: 6379
-
server: 'redis2.ez.no'
port: 6379=20
Memcache(d)
This cache backend is using Memcached, a distributed caching solution. This is the main supported cache solution for multi server (cluster) setups, besides using Redis.
Note
Stash supports both the php-memcache and php-memcached exte= nsions. However only php-memcached is officially supported= as php-memcache is missing many features and is less stable.
Available settings
servers |
Array of Memcached servers, wit= h host/IP, port and weight
|
prefix_key=
|
A namespace to prefix cache =
keys with to avoid key conflicts with other eZ Platform sites on same eZ Pl=
atform installation (default is an empty string). Must b= e the same on all servers with the same installation. |
compression |
default true. See Memcached compression op= tion * |
libketama_compatibl=
e |
default false. = See Memcached libketama_compatible option * |
buffer_writes |
default false. = See Me= mcached buffer_writes option * |
binary_protocol |
default false. = See = Memcached binary_protocol option * |
no_block <=
/code> |
default false. = See Memcach= ed no_block option * |
tcp_nodelay |
default false. = See Memc= ached tcp_nodelay option * |
connection_timeout<=
/strong> |
default 1000. <= a href=3D"http://www.php.net/manual/en/memcached.constants.php#memcached.co= nstants.opt-connection-timeout" class=3D"external-link" rel=3D"nofollow">Se= e Memcached connection_timeout option * |
retry_timeout |
default 0. See Me= mcached retry_timeout option * |
send_timeout |
default 0. See Memcach= ed send_timeout option * |
recv_timeout |
default 0. <= a href=3D"http://www.php.net/manual/en/memcached.constants.php#memcached.co= nstants.opt-recv-timeout" class=3D"external-link" rel=3D"nofollow">See Memc= ached recv_timeout option * |
poll_timeout |
default 1000. <= a href=3D"http://www.php.net/manual/en/memcached.constants.php#memcached.co= nstants.opt-poll-timeout" class=3D"external-link" rel=3D"nofollow">See Memc= ached poll_timeout option * |
cache_lookups |
default false. = See Me= mcached cache_lookups option * |
server_failure_limi=
t |
default 0. See=
PHP Memcached documentation * |
socket_send_size |
See Memcached socket_send_size option= * |
socket_recv_size |
See Memcached socket_recv_size option= * |
serializer <=
/strong> |
See Memcached serializer option * |
hash |
See Memcached hash option * |
distribution=
|
Specifies the method of distrib= uting item keys to the servers. See Memcached distribution option * |
* All settings except servers are only ava=
ilable with memcached PHP extension. For more information on these settings=
and which version of php-memcached they are available in, see: =
;http://php.net/Memcached
When using Memcache cache backend, you may use inMemory to redu= ce network traffic as long as you are aware of its limitations mentioned ab= ove.
Example with Memcache(d)
Note that app/config/config.yml contains the default stash =
configuration. To apply the configuration below, make sure you update the e=
xisting configuration, or remove it if you want to use another configuratio=
n file.
stash:
caches:
default:
drivers: [ Memcache ]
inMemory: true
registerDoctrineAdapter: false
Memcache:
prefix_key: ezdemo_
retry_timeout: 1
servers:
-
server: 127.0.0.1
port: 11211=20
Connection errors issue
If memcached does display connection errors when using the default (asci= i) protocol, then switching to binary protocol (in the stash configurat= ion and memcached daemon) should resolve the issue.
Usage
Using Cache Service
Using the internal cache service allows you to use an interface and= to not have to care whether the system has been configured to place the ca= che in Memcached or on File system. And as eZ Platform requires that instan= ces use a cluster-aware cache in Cluster setup, you can safely assume your = cache is shared (and invalidated) across all web servers= .
Interface will change in the future
Current implementation uses a caching library called Stash, = via StashBundle. We plan to move to a P= SR-6 compatible cache service capable of supporting cache Tagging and multi= get/set in the future, when that happens the interface of the cache servic= e will change!
Use unique vendor prefix for Cache key!
When reusing the cache service within your own code, it is very importan= t to not conflict with the cache keys used by others. That is why the examp= le of usage below starts with a unique "myApp" key. For the namespace of yo= ur own cache, you must do the same! So never clear cache using the cache se= rvice without your key specified, otherwise you'll clear all cache.
Get Cache service
Via Dependency injection
In your Symfony services configuration you can simply define that you re= quire the "cache" service in your configuration like so:
myApp.myService:
class: %myApp.myService.class%
arguments:
- @ezpublish.cache_pool=20
The "cache" service is an instance of the following class: Te=
divm\StashBundle\Service\CacheService
Via Symfony Container
Like any other service, it is also possible to get the "cache" service v= ia container like so:
/** @var $cacheService \Tedivm\StashBundle\Service\CacheService */
$cacheService =3D $container->get('ezpublish.cache_pool');=20
Using the cache service
Example usage of the cache service:
$cacheItem =3D $cacheService->getItem('myApp', 'object', $id=
);
$myObject =3D $cacheItem->get();
if ($cacheItem->isMiss()) {
$myObject =3D $container->get('my_app.backend_service')->load=
Object($id)
$cacheItem->set($myObject);
}
return $myObject;=20
For more info on usage, take a look at Stash's documentation= .
Clearing Persistence cache
Persistence cache uses a separate Cache Pool decorator which by design p= refixes cache keys with "ez_spi". Clearing persistence cache can thus be do= ne in the following way:
/** @var $cacheService \eZ\Publish\Core\Persistence\Cache\CacheServ=
iceDecorator */
$cacheService =3D $container->get('ezpublish.cache_pool.spi.cache.decora=
tor');
// To clear all cache
$cacheService->clear();
// To clear a specific cache item (check source code in eZ\Publish\Core\Per=
sistence\Cache\*Handlers for further info)
$cacheService->clear('content', 'info', $contentId);
// Stash cache is hierarchical, so you can clear all content/info cache lik=
e so:
$cacheService->clear('content', 'info');=20
Binary files URL handling
IO URL decoration
By default, images and binary files referenced by content will be served=
from the same server as the application, like /var/ezdem=
o_site/storage /images/3/6/4/6/6463-1-eng-GB/kidding.png . This is the default semantic configuration:
ezpublish:
system:
default:
io:
=09 url_prefix: "$var_dir$/$storage_dir$"
=20
$var_dir$ and $storage_dir$ a=
re dynamic, siteaccess-aware settings<=
/a>, and will be replaced by those settings value in the execution context.=
URL decorators are an eZ Platform features. If an image field is display= ed via a legacy callback or legacy template, no decoration will be applied.=
Using a static serv= er for images
One common use-case is to use an optimized nginx to serve i=
mages in an optimized way. The example image above could be made available =
as http://static.example.com/ images/3=
/6/4/6/6463-1-eng-GB/kidding.png , by setting up a server tha=
t uses ezpublish/ezpublish_legacy/var/ezdemo_site/storage. The=
eZ Platform configuration would be as follows:
ezpublish:
system:
default:
io:
=09 url_prefix: "http://static.example.com/"
=20
Legacy compatiblity
Legacy still requires non-absolute path to store images (var/site/storag=
e/images/etc.). In order to work around this, a UrlRedecorator=
, that converts back and forth between the legacy uri prefix and the one in=
use in the application has been added. It is used in all places where a le=
gacy URL is returned/expected, and takes care of making sure the value is a=
s expected.
Internals
Any BinaryFile returned by the public API is prefixed =
with the value of this setting, internally stored as ezsettings=
.scope.io.url_prefix.
Dynamic container settings
Those settings are siteaccess-aware.
io.url_prefix
Default value: $var_dir$/$storage_dir$
Exam=
ple: /var/ezdemo_site/storage
Used to configure the default URL decorator service =
( ezpublish.core.io.default_url_decorator
io.legacy_url_prefix
Default value: $var_dir$/$storage_dir$ =
Example: var/ezdemo_site/storage
Used by the legacy storage engine to convert images public URI to = a format it understands. Unlike io.url_prefix, it is not an absolute link. = Cannot be overridden using semantic configuration. Changing this= value will break compatibility for the legacy backoffice.
io.root_dir
Example: %ezpublish_legacy.root_di=
r%/$var_dir$/$storage_dir$
Default value: /var/www=
/ezpublish/ezpublish_legacy/var/ezdemo_site/storage =
Physical path where binary files are stored on disk.= Cannot be overridden using semantic configuration. Changing this value wil= l break compatibility for the legacy backoffice.
= Services
URL decorators
An UrlDecorator decorates and undecorates a given string (url) in some w=
ay. It has two mirror methods: decorate and undecorate.
Two implementations are provided: Prefix, and Absolut=
ePrefix. They both add a prefix to a URL, but AbsolutePrefix will ensure that unless the prefix is an external URL, the result wil=
l be prepended with /.
Three UrlDecorator services are introduced:
ezpublish.core.io.prefix_url_decoratorused by the= binarydata handlers to decorate all uris sent out by the API. Uses Absolut= ePrefix.ezpublish.core.io.image_fieldtype.legacy_url_decorator used via the UrlRedecorator (see below) by various legacy elements (Co= nverter, Storage Gateway, etc.) to generate its internal storage format for= uris. Uses a Prefix, not an AbsolutePrefix, meaning that no leading / is a= dded.
In addition, a UrlRedecorator service, ezpublish.core.io.i=
mage_fieldtype.legacy_url_redecorator, uses both decorators above to=
convert URIs between what is used on the new stack, and what format legacy=
expects (relative urls from the ezpublish root).
Regenerating URL Aliases
The command ezplatform:regenerate:legacy_storage_url_aliases comman=
d regenerates URL aliases for Locations and migrates existing custom Locati=
on and global URL aliases to a separate database table. The separate table =
must be named __migration_ezurlalias_ml and should be created =
manually to be identical (but empty) as the existing table ezurlalias=
_ml before the command is executed.
After the script finishes, to complete migration the table should be ren=
amed to ezurlalias_ml manually. Using available options for __migration_backup_=
custom_alias and __migration_backup_global_alias (creat=
ed automatically).
It is also possible to skip custom Location and global URL aliases altog=
ether and regenerate only automatically created URL aliases for Locations (=
use the autogenerate action to achieve this). During the scrip=
t execution the database should not be modified. Since this script can pote=
ntially run for a very long time, to avoid memory exhaustion run it in prod=
uction environment using the --env=3Dprod switch.
Reference
Services: Public API
The Public API exposes Symfony services for all of its repository servic= es.
| Service id | Type |
|---|---|
ezpublish.api.service.conten=
t |
eZ\Publish\API\Repository\Co=
ntentService |
ezpublish.api.service.content_type<=
/td>
| eZ\Publish\API\Repository\ContentTypeServi=
ce |
ezpublish.api.service.location |
eZ\Publish\API\Repository\LocationService<=
/code> |
ezpublish.api.service.url_alias
| eZ\Publish\API\Repository\UrlAliasService<=
/code> |
ezpublish.api.service.field_type
| eZ\Publish\API\Repository\FieldTypeService=
|
ezpublish.api.service.language |
eZ\Publish\API\Repository\Language<=
/td>
|
ezpublish.api.service.object_state<=
/td>
| eZ\Publish\API\Repository\ObjectState |
ezpublish.api.service.role |
eZ\Publish\API\Repository\Role |
ezpublish.api.service.search |
eZ\Publish\API\Repository\Search
|
ezpublish.api.service.section |
eZ\Publish\API\Repository\Section
|
ezpublish.api.service.trash |
eZ\Publish\API\Repository\Trash
|
ezpublish.api.service.url_wildcard<=
/td>
| eZ\Publish\API\Repository\UrlWildcard |
ezpublish.api.service.user |
eZ\Publish\API\Repository\User |
Signals Reference
You can find the reference for all available signals th= at you can listen to, triggered by ("Public") Repository API in eZ Platform= , in their dedicated page: Signals Reference.
Limitations Reference
Limitations are crucial building blocks of the p= ermissions system in eZ Platform. They provide the restrictions you can= apply to a given access right to limit the right according to certain cond= itions.
Limitations consist of two parts:
Limitation(Value)LimitationType
Certain limitations also serve as RoleLimitations, which means they can =
be used to limit the rights of a Role assignment. Currently this covers Section limitations.
Limitation represents the value, while LimitationType=
deals with the business logic surrounding how it actually works and=
is enforced.
LimitationTypes have two modes of operation =
in regards to permission logic (see eZ\Publish\SPI\Limitation\Ty=
pe interface for more info):
| Method | Use |
|---|---|
evaluate |
Evaluating if the user has access to a giv=
en object in a certain context (for instance the context can be Locations w=
hen the object is Content), under the condition of the L=
imitation value(s). |
getCriterion |
Generates a Criterion using <=
code>Limitation value and current user which SearchService by default applies to search criteria for filtering search based on per=
missions. |
List of Limitations
Extensibility
Permissions
Two parts of the permissions system are extensible from a programmatic p= erspective: Policies and Limitations
- Policies: Custom Policies can be added for use in your own code , custom Policy example: comment/= create
- Limitations: You= can extend existing Policies, and hence extend the permissions of the CMS,= example could be adding a Subscri= ptionLimitation to content/read Policy
Custom Policies
Description
eZ content repository uses the concept of Roles and Policies in order to= authorize a user to do something (e.g. read content).
- A Role is composed of Policies and can be assigned to a User or a User = Group.
- A Policy is composed of a combination of module&n=
bsp;and function (e.g.
content/read,contentbeing the module andread<= /code> being the function). - Depending on module and functio= n combination, a Policy can also be composed of Limitations.<= /li>
It is possible for any bundle to expose available Policies via a
PolicyProvider
A PolicyProvider is an object providing a hash co=
ntaining declared modules, functions and limitations.
- Each Policy provider provides a collection of permission modul= es.
- Each module can provide functions (e.g. "content/rea= d": "content" is the module, "read" is the function)
- Each function can provide a collection of Limitations.
Policies configuration hash contains declared these modules, functions a=
nd Limitations.
First level key is the module name, value is a hash of a=
vailable functions, with function name as key.
Function value is an arra=
y of available Limitations, identified by the alias declared in LimitationT=
ype service tag.
If no Limitation is provided, value can be null or an empty array.
[
"content" =3D> [
"read" =3D> ["Class", "ParentClass", "Node", "Language"],
"edit" =3D> ["Class", "ParentClass", "Language"]
],
"custom_module" =3D> [
"custom_function_1" =3D> null,
"custom_function_2" =3D> ["CustomLimitation"]
],
]=20
Limitations need to be implemented as limitation types&nbs=
p;and declared as services identified with ezpublish.limitationT=
ype tag. Name provided in the hash for each Limitation is =
the same value set in alias attribute in the service tag.
Example
namespace Acme\FooBundle\AcmeFooBundle\Security;
use eZ\Bundle\EzPublishCoreBundle\DependencyInjection\Configuration\ConfigB=
uilderInterface;
use eZ\Bundle\EzPublishCoreBundle\DependencyInjection\Security\PolicyProvid=
er\PolicyProviderInterface;
class MyPolicyProvider implements PolicyProviderInterface
{
public function addPolicies(ConfigBuilderInterface $configBuilder)
{
$configBuilder->addConfig([
"custom_module" =3D> [
"custom_function_1" =3D> null,
"custom_function_2" =3D> ["CustomLimitation"],
],
]);
}
}=20
YamlPolicyProvider
An abstract class based on YAML is provided: eZ=
\Bundle\EzPublishCoreBundle\DependencyInjection\Security\PolicyProvider\Yam=
lPolicyProvider .
It defines an abstract&nbs=
p; getFiles() method.
Extend YamlPolicyProvider and implement getFile=
s() to return absolute paths to your YAML files.
namespace Acme\FooBundle\AcmeFooBundle\Security;
use eZ\Bundle\EzPublishCoreBundle\DependencyInjection\Security\PolicyProvid=
er\YamlPolicyProvider;
class MyPolicyProvider extends YamlPolicyProvider
{
protected function getFiles()
{
return [
__DIR__ . '/../Resources/config/policies.yml',
];
}
}=20
custom_module:
custom_function_1: ~
custom_function_2: [CustomLimitation]=20
Extending existing po= licies
A PolicyProvider may provide new functions to a module, and=
additional Limitations to an existing function.
It is ho=
wever strongly encouraged to add functions to your own Policy modules.
It is not possible to remove an existing module, function or limitation = from a Policy.
I= ntegrating the PolicyProvider into EzPublishCoreBundle
For a PolicyProvider to be active, it must be properly declared in=
EzPublishCoreBundle.
A bundle just has to retrieve CoreBundle's DIC ex=
tension and call addPolicyProvider() . This=
must be done in the bundle's build() =
;method.
namespace Acme\FooBundle\AcmeFooBundle;
use Symfony\Component\HttpKernel\Bundle\Bundle;
class AcmeFooBundle extends Bundle
{
public function build(ContainerBuilder $container)
{
parent::build($container);
// ...
// Retrieve "ezpublish" container extension.
$eZExtension =3D $container->getExtension('ezpublish');
// Add the policy provider.
$eZExtension->addPolicyProvider(new MyPolicyProvider());
}
}=20
Core policies
Policies used internally in repository services are defined=
in EzPublishCoreBundle/Resources/=
config/policies.yml .
SPI and API repositories
Those repositories are read-only split of =
ezsystems/ezpublish-kernel, made available to make dependencie=
s easier and more lightweight.
API
This package is a split of the eZ Publish =
5 public API. It includes the services interfaces and eZ\Publish\API namespace.=
It offers a lightweight way to make your project depend on the eZ API a=
nd Domain objects, without depending on the whole ezpublish-kernel.
The =
repository is read-only, automatically updated from https://github.com/ezsystems/ezpublish-kernel.
Requiring ezpublish-api in your project:
"require": {
"ezsystems/ezpublish-api": "~5.0"
}=20
SPI
This package is a split of the eZ Publish = 5 SPI (persistence interfaces).
It can be used as a dependency, instead of= the whole ezpublish-kernel, by packages implementing custom eZ Pub= lish storage engines, or by any package that requires clas= ses from the eZ\Publish\SPI namespace.
The repository is read-only, automatically= updated from https://github.com/ezsystems/ezpublis= h-kernel.
Requiring ezpublish-api in your project:
"require": {
"ezsystems/ezpublish-spi": "~5.0"
}=20
Signal Slots
The Signal-Slot system provides a means for realizing loosely coupled de= pendencies in the sense that a code entity A can react on an event occurrin= g in code entity B, without A and B knowing each other directly. This works= by dispatching event information through a central third instance, the so = called dispatcher:
In the shown schematics, object B and one other object are interested in= a certain signal. B is a so-called Slot that can be announced to be intere= sted in receiving a Signal (indicated by the circular connector to the disp= atcher). Object A now sends the corresponding Signal. The Dispatcher takes = care of realizing the dependency and informs the Slot A (and one other Slot= ) about the occurrence of the Signal.
Signals roughly equal events, while Slots roughly equal event handlers. = An arbitrary number (0=E2=80=A6n) of Slots can listen for a specific Signal= . Every object that receives the Dispatcher as a dependency can send signal= s. However, the following conditions apply (that typically do not apply to = event handling systems):
- A Slot cannot return anything to the object that issued a signal
- It is not possible for a Slot to stop the propagation of a Signal, i.e.= all listening Slots will eventually receive the Signal
Those two conditions allow the asynchronous processing of Slots. That me= ans: It is possible to determine, by configuration, that a Slot must not re= ceive a Signal in the very same moment it occurs, but to receive it on a la= ter point in time, maybe after other Signals from a queue have been process= ed or even on a completely different server.
Signal
A Signal represents a specific event, e.g. that a content version has be=
en published. It consists of information that is significant to the event, =
e.g. the content ID and version number. Therefore, a Signal is represented =
by an object of a class that is specific to the Signal and that extends fro=
m eZ\Publish\Core\SignalSlot\Signal. The full qualified name o=
f the Signal class is used to uniquely identify the Signal. For example, th=
e class eZ\Publish\Core\SignalSlot\Signal\ContentService\PublishVersi=
onSignal identifies the example Signal.
In order to work properly with asynchronous processing, Signals must not=
consist of any logic and must not contain complex data structures (such as=
further objects and resources). Instead, they must be exportable using the=
__set_state() method, so that it is possible to transfer a Si=
gnal to a different system.
Note
eZ\Publish\Core\SignalSlot\SignalDispatcher). However, at a fi=
rst stage,=20
Signals are only sent by special implementations of the Public API =
to indicate core events. These services must and will be used by d=
efault and will wrap the original service implementations.
Slot
A Slot extends the system by realizing functionality that is executed wh=
en a certain Signal occurs. To implement a Slot, you must create a class th=
at derives from eZ\Publish\Core\SignalSlot\Slot. The full qual=
ified name of the Slot class is also used as the unique identifier of the S=
lot. The Slot base class requires you to implement the single method =
receive(). When your Slot is configured to listen to a certain Signa=
l and this Signal occurs, the receive() method of your Slot is=
called.
Inside the receive() method of your Slot you can basically =
realize any kind of logic. However, it is recommended that you only dispatc=
h the action to be triggered to a dedicated object. This allows you to trig=
ger the same action from within multiple Slots and to re-use the implementa=
tion from a completely different context.
Note that, due to the nature of Signal-Slot, the following requirements = must be fulfilled by your Slot implementation:
- A Slot must not return anything to the Signal issuer
- A Slot must be aware that it is potentially executed delayed or even on= a different server
Important: A single Slot= should not take care of processing more than one Signal. Instead, if you n= eed to trigger same or similar actions as different Signals occur. you shou= ld encapsulate these actions into a dedicated class, of which your Slots re= ceive an instance to trigger this action.
Example: Updating URL alia= ses
Updating URL aliases is a typical process that can be realized through a= Signal-Slot extension for different reasons:
- The action must be triggered on basis of different events (e.g. content= update, location move, etc.)
- Direct implementation would involve complex dependencies between otherw= ise unrelated services
- The action is not critical to be executed immediately, but can be made = asynchronous, if necessary
As a first step it needs to be determined for which Signals we need to l= isten in order to update URL aliases. Some of them are:
eZ\Publish\Core\SignalSlot\Signal\ContentService\PublishVersionSi= gnaleZ\Publish\Core\SignalSlot\Signal\LocationService\CopySubtreeSign= aleZ\Publish\Core\SignalSlot\Signal\LocationService\MoveSubtreeSign= al- =E2=80=A6
There are of course additional Signals that trigger an update of URL ali= ases, but these are left out for simplicity here.
Now that we identified some Signals to react upon, we can start implemen=
ting Slots for these signals. For the first Signal, which is issued as soon=
as a new version of Content is published, there exists a method in e=
Z\Publish\SPI\Persistence\Content\UrlAlias\Handler for exactly that =
purpose: publishUrlAliasForLocation(). The Signal contains the=
ID of the content item and its newly published version number. Using this =
information, the corresponding Slot can fulfill its purposes with the follo=
wing steps:
- Load the corresponding content and its locations
- Call the URL alias creation method for each location
To achieve this, the Slot has 2 dependencies:
eZ\Publish\SPI\Persistence\Content\Handler
to load the= content itself in order to retrieve the nameseZ\Publish\SPI\Persistence\Content\Location\Handler
to= load the locationseZ\Publish\SPI\Persistence\Content\UrlAlias\Handler
So, a stub for the implementation could look like this:
namespace Acme\TestBundle\Slot;
use eZ\Publish\Core\SignalSlot\Slot as BaseSlot;
use eZ\Publish\API\Repository\Repository;
use eZ\Publish\SignalSlot\Signal;
class CreateUrlAliasesOnPublishSlot extends BaseSlot
{
/**
* @var \eZ\Publish\API\Repository\Repository
*/
private $repository;
public function __construct( Repository $repository )
{
$this->repository =3D $reposi=
tory;
}
public function receive( Signal $signal )
{
if ( !$signal instanceof Signal\=
ContentService\PublishVersionSignal )
{
return;
}
// Load content
// Load locations
// Create URL aliases
}
}=20
In order to make the newly created Slot react on the corresponding Signa= l, the following steps must be performed:
- Make the Slot available through the Symfony service container as a serv= ice
- Register the Slot to react to the Signal of type
eZ\Publish\Core\= SignalSlot\Signal\ContentService\PublishVersionSignal
See the Listenin= g to Core events recipe in the developer cookbook for more information.=
- =20
- Introduction=20
- =20
- Locations=20
- =20
- Top level Locations = =20
- Location visibility = =20
=20
- Content Relations =20
- Sections =20
- Permissions=20 =20
- Persistence Cache =20
=20
- Locations=20
- Configuration=20 =20
- Usage=20
- =20
- Using Cache Service=20 =20
- Binary files URL handlin= g=20 =20
- Regenerating URL Aliases= =20
=20
- Reference=20
- =20
- Services: Public API=20
- Signals Reference =20
- Limitations Reference=
=20
- =20
- List of Limitations = =20
=20
=20
- Extensibility=20
- =20
- Permissions =20
- Custom Policies=20 =20
- SPI and API repositories<= /a>=20 =20
- Signal Slots=20
- =20
- Signal =20
- Slot =20
- Example: Updating UR= L aliases =20
=20
=20