eZ Platform allows you to maintain multiple sites in one installation us= ing a feature called siteaccesses.
In short, a siteaccess is a set of configuration settings that is used w= hen the site is reached through a specific address.
When the user accesses the site, the system analyzes the uri and compare= s it to rules specified in the configuration. If it finds a set of fitting = rules, this siteaccess is used.
A siteaccess overrides the default configuration. This means that if the= siteaccess does not specify some aspect of the configuration, the default = values will be used. The default configuration is also used when no siteacc= ess can be matched to a situation.
A siteaccess can decide many things about the website, for example the d= atabase, language or var directory that are used.
A siteaccess is selected using one or more matchers =E2=80=93 rules base= d on the uri or its parts. Example matching criteria are elements of the ur= i, host name (or its parts), port number, etc.
For detailed information on how siteaccess matchers work, see Siteaccess Matching.
Typical uses of a siteaccess are:
Both the rules for siteaccess matching and its effects are located in th= e main app/config/ezplatform.yml configuration file.
A site has content in two languages: English and Norwegian. It has one U=
RI per language: http://example.com/eng =
and http://example.com/nor. Uri parts of each language (eng, nor) are mappe=
d to a siteaccess, commonly named like the uri part: en=
g, nor. Using semantic configuration, each=
of these siteaccesses can be assigned a prioritized list of languages it s=
hould display:
Such configuration would look like this:
ezpublish:
=09siteaccess:
=09=09# There are two siteaccess
=09=09list: [eng, nor]
=09=09# eng is the default one if no prefix is specified
default_siteaccess: eng
=09=09# the first URI of the element is used to find a siteaccess with a si=
milar name
match:
=09=09 URIElement: 1
ezpublish:
=09# root node for configuration per siteaccess=20
=09system:
=09=09# Configuration for the 'eng' siteaccess
eng:
=09=09=09languages: [eng-GB]
nor:
languages: [nor-NO, eng-GB]=20
When no particular context is required, it is fine to use the `default` = scope instead of specifying a siteaccess.
Important
Configuration is tightly related to the service container.
To fully =
understand the following content, you need to be familiar with Symfony's service container and
Basic configuration handling in eZ Platform is similar to what is common= ly possible with Symfony. Regarding this, you can define key/value pairs in= your configuration files, under the main paramete= rs key (like in parameters.yml).
Internally and by convention, keys follow a dot syntax&= nbsp;where the different segments follow your configuration hierarchy. Keys= are usually prefixed by a namespace corresponding to yo= ur application. Values can be anything, including arrays and deep h= ashes.
For configuration that is meant to be exposed to an end-user (or end-dev= eloper), it's usually a good idea to also implement semantic configuration.
Note that it is also possible to implement SiteAccess aware semantic configuration.
parameters:
myapp.parameter.name: someValue
myapp.boolean.param: true
myapp.some.hash:
foo: bar
an_array: [apple, banana, pear]=20
// Inside a controller $myParameter =3D $this->container->getParameter( 'myapp.parameter.nam= e' );=20
In eZ Platform it is fairly common to have different settings depending = on the current siteaccess (e.g. languages, view provider configuration).
Dynamic configuration can be resolved depending on a scope.
Available scopes are (in order of precedence) :
It gives the opportunity to define settings for a given siteaccess, for = instance, like in the legacy INI override system.
This mechanism is not limited to eZ Platform internal settings (aka = ;ezsettings namespace) and is applicable for= specific needs (bundle-related, project-related, etc.).
Always prefer semantic configuration especially for internal eZ settings=
.
Manually editing internal eZ settings is possible, but at your own ris=
k, as unexpected behavior can occur.
Dynamic configuration is handled by a config resolver. =
It consists in a service object mainly exposing hasParameter() and getParameter() methods. The idea is to check th=
e different scopes available for a given namespace t=
o find the appropriate parameter.
In order to work with the config resolver, your dynamic settings must co=
mply internally with the following name format: <namespace>.<=
;scope>.parameter.name.
parameters:
# Some internal configuration
ezsettings.default.content.default_ttl: 60
ezsettings.ezdemo_site.content.default_ttl: 3600
# Here "myapp" is the namespace, followed by the siteaccess name as the=
parameter scope
# Parameter "foo" will have a different value in ezdemo_site and ezdemo=
_site_admin
myapp.ezdemo_site.foo: bar
myapp.ezdemo_site_admin.foo: another value
# Defining a default value, for other siteaccesses
myapp.default.foo: Default value
# Defining a global setting, used for all siteaccesses
#myapp.global.some.setting: This is a global value=20
// Inside a controller, assuming siteaccess being "ezdemo_site" /** @var $configResolver \eZ\Publish\Core\MVC\ConfigResolverInterface **/ $configResolver =3D $this->getConfigResolver(); // ezsettings is the default namespace, so no need to specify it // The following will resolve ezsettings.<siteaccessName>.content.def= ault_ttl // In the case of ezdemo_site, will return 3600. // Otherwise it will return the value for ezsettings.default.content.defaul= t_ttl (60) $locationViewSetting =3D $configResolver->getParameter( 'content.default= _ttl' ); $fooSetting =3D $configResolver->getParameter( 'foo', 'myapp' ); // $fooSetting's value will be 'bar' // Force scope $fooSettingAdmin =3D $configResolver->getParameter( 'foo', 'myapp', 'ezd= emo_site_admin' ); // $fooSetting's value will be 'another value' // Note that the same applies for hasParameter()=20
Both getParameter() and hasParameter()=
can take 3 different arguments:
$paramName (i.e. the name of the parameter you need)<=
/li>
$namespace (i.e. your application namespace, $scope (i.e. a siteaccess name. If null, the current =
siteaccess will be used)Instead of injecting the whole ConfigResolver service, you may directly = inject your SiteAccess-aware settings = (aka dynamic settings) into your own services.
You can use the ConfigResolver in your own services whe=
never needed. To do this, just inject the ezpublish.config.re=
solver service:
parameters:
my_service.class: My\Cool\Service
services:
my_service:
class: %my_service.class%
arguments: [@ezpublish.config.resolver]=20
<?php
namespace My\Cool;
use eZ\Publish\Core\MVC\ConfigResolverInterface;
class Service
{
/**
* @var \eZ\Publish\Core\MVC\ConfigResolverInterface
*/
private $configResolver;
public function __construct( ConfigResolverInterface $configResolver )
{
$this->configResolver =3D $configResolver;
$myParam =3D $this->configResolver->getParameter( 'foo', 'mya=
pp' );
}
// ...
}=20
If you need to use a custom locale they can also be configurable in
ezpublish:
# Locale conversion map between eZ Publish format (i.e. fre-FR) to POSI=
X (i.e. fr_FR).=20
# The key is the eZ Publish locale. Check locale.yml in EzPublishCoreBu=
ndle to see natively supported locales.
locale_conversion:
eng-DE: en_DE=20
A locale conversion map example can be found=
in the core bundle, on locale.yml.
Siteaccess matching is done through eZ\Publish\MVC\SiteAccess\Ma= tcher objects. You can configure this matching and even devel= op custom matchers.
To be usable, every siteaccess must be provided a matcher.
You can configure siteaccess matching in your main app/config/ez= platform.yml:
ezpublish:
siteaccess:
default_siteaccess: ezdemo_site
list:
- ezdemo_site
- eng
- fre
- fr_eng
- ezdemo_site_admin
groups:
ezdemo_site_group:
- ezdemo_site
- eng
- fre
- fr_eng
- ezdemo_site_admin
match:
Map\URI:
ezdemo_site: ezdemo_site
fre: fre
ezdemo_site_admin: ezdemo_site_admin
=20
You need to set several parameters:
ezpublish.siteaccess.default_siteaccess is the default = siteaccess that will be used if matching was not successful. This ensures t= hat a siteaccess is always defined.
ezpublish.siteaccess.list is the list of all available = siteaccesses in your website.
(optional) ezpublish.siteaccess.groups defines= which groups siteaccesses belong to. This is useful when you want to mutua= lize settings between several siteaccesses and avoid config duplication. Si= teaccess groups are treated the same as regular siteaccesses as far as conf= iguration is concerned.
A siteaccess can be part of several groups.
A siteaccess configuration has always precedence on the group configurat= ion.
ezpublish.siteaccess.match holds the matching co=
nfiguration. It consists in a hash where the key is the name of the matcher=
class. If the matcher class doesn't start with a \ , it will be considered relative to eZ\Publish\MVC\Si=
teAccess\Matcher (e.g. Map\Host w=
ill refer to eZ\Publish\MVC\SiteAccess\Matcher\Ma=
p\Host)
Every custom matcher can be specified with a \My\SiteAccess\Matcher<=
/code>) or by a service identifier prefixed by @ (e.g. ).
eZ\Bundle\EzPub=
lishCoreBundle\SiteAccess\Matcher. The matching configuration will b=
e passed to setMatchingConfiguration().Make sure to type the matcher in correct case. If it is in wrong case li= ke "Uri" instead of "URI," it will happily work on systems like Mac OS X be= cause of case insensitive file system, but will fail when you deploy it to = a Linux server. This is a known artifact of PSR-0 autoloading of PHP classes.
| Name | Description | Configuration | Example |
|---|---|---|---|
URIElement |
Maps a URI element to a siteaccess. This is t= he default matcher used when choosing URI matching in setup wizard.&nbs= p; |
The element number you want to match (startin= g from 1). =20
ezpublish:
siteaccess:
match:
URIElement: 1=20
Important: When using a value > 1, it w= ill concatenate the elements with _ |
URI: Element number: 1 Element number: 2 |
URIText |
Matches URI using pre and=
/or post sub-strings in the first URI segment |
The prefix and/or suffix (none = are required) =20
ezpublish:
siteaccess:
match:
URIText:
prefix: foo
suffix: bar=20
|
URI: Prefix: foo |
HostElement |
Maps an element in the host name t= o a siteaccess. | The element number you want to = match (starting from 1). =20
ezpublish:
siteaccess:
match:
HostElement: 2=20
|
Host name: Element number: 2 |
HostText |
Matches a siteaccess in the host n=
ame, using pre and/or post sub-strings. |
The prefix and/or suffix (none = are required) =20
ezpublish:
siteaccess:
match:
HostText:
prefix: www.
suffix: .com=20
|
Host name: Prefix: www. |
Map\Host |
Maps a host name to a siteaccess.<= /td> | A hash map of host/siteaccess =20
ezpublish:
siteaccess:
match:
Map\Host:
www.foo.com: foo_front
adm.foo.com: foo_admin
www.bar-stuff.fr: bar_front
adm.bar-stuff.fr: bar_admin=20
In eZ Enterprise, when using the
|
Map:
Host name: www.example.com Matched s= iteaccess: foo_front |
Map\URI |
Maps a URI to a siteaccess | A hash map of URI/siteaccess =20
ezpublish:
siteaccess:
match:
Map\URI:
something: ezdemo_site
foobar: ezdemo_site_admin=20
The name of the |
URI: Map:
Matched siteaccess: ezdemo_site |
Map\Port |
Maps a port to a siteaccess | A has map of Port/siteaccess =20
ezpublish:
siteaccess:
match:
Match\Port:
80: foo
8080: bar=20
|
URL: Map:
Matched siteaccess: bar |
Regex\Host |
Matches against a regexp and extra= cts a portion of it | The regexp to match against =20
ezpublish:
siteaccess:
match:
Regex\Host:
regex: "^(\\w+_sa)$"
# Default is 1
itemNumber: 1=20
|
Host name: regex: Matched siteaccess: example |
Regex\URI |
Matches against a regexp and extra= cts a portion of it | The regexp to match again=
st =20
ezpublish:
siteaccess:
match:
Regex\URI:
regex: "^/foo(\\w+)bar"
# Default is 1
itemNumber: 1=20
|
URI: regex: ^/foo(\\w+)bar Matched siteaccess: test |
The Compound siteaccess matcher allows you to combine several matchers t= ogether:
Compound matchers cover the legacy host_uri matching feature.
They are based on logical combinations, or/and, using logical compound m= atchers:
Compound\LogicalAndCompound\LogicalOrEach compound matcher will specify two or more sub-matchers. A rule will=
match if all the matchers, combined with the logical matcher, are positive=
. The example above would have used Map\Host and&nbs=
p;Map\Uri., combined with a LogicalAnd. When both=
the URI and host match, the siteaccess configured with "match" is used.
ezpublish:
siteaccess:
match:
Compound\LogicalAnd:
# Nested matchers, with their configuration.
# No need to precise their matching values (true will suffi=
ce).
site_en:
matchers:
Map\URI:
en: true
Map\Host:
example.com: true
match: site_en
site_fr:
matchers:
Map\URI:
fr: true
Map\Host:
example.com: true
match: site_fr
Map\Host:
admin.example.com: site_admin=20
It is possible to define which siteaccess to use by setting an X= -Siteaccess header in your request. This can be useful for REST re= quests.
In such case, X-Siteaccess must be the siteacce= ss name (e.g. ezdemo_site).
It is also possible to define which siteaccess to use directly via an
This is recommended if you want to get performance gain= since no matching logic is done in this case.
You can define this environment variable directly from your web server c= onfiguration:
# This configuration assumes that mod_env is activated
<VirtualHost *:80>
DocumentRoot "/path/to/ezpublish5/web/folder"
ServerName example.com
ServerAlias www.example.com
SetEnv EZPUBLISH_SITEACCESS ezdemo_site
</VirtualHost>=20
This can also be done via PHP-FPM configuration file, if you use i= t. See PHP-FPM doc= umentation for more information.
Note about precedence
The precedence order for siteaccess matching is the following (the= first matched wins):
In some cases, after matching a siteaccess, it is neecessary to modify t= he original request URI. This is for example needed with URI-based matchers= since the siteaccess is contained in the original URI and it is not part o= f the route itself.
The problem is addressed by analyzing this URI and by modifying= it when needed through the URILexer interface.
/**
* Interface for SiteAccess matchers that need to alter the URI after match=
ing.
* This is useful when you have the siteaccess in the URI like "/<siteac=
cessName>/my/awesome/uri"
*/
interface URILexer
{
/**
* Analyses $uri and removes the siteaccess part, if needed.
*
* @param string $uri The original URI
* @return string The modified URI
*/
public function analyseURI( $uri );
/**
* Analyses $linkUri when generating a link to a route, in order to hav=
e the siteaccess part back in the URI.
*
* @param string $linkUri
* @return string The modified link URI
*/
public function analyseLink( $linkUri );
}=20
Once modified, the URI is stored in the semanticPathinfo request attribute, and the original pathinfo is not modified.<= /p>
When using the multisite feature, it is sometimes useful to be = able to generate cross-links between the different sites.<= br> This allows you to link different resources referenced in the same cont= ent repository, but configured independently with different tree roots.
{# Linking a location #}=20
<a href=3D"{{ url( 'ez_urlalias', {'locationId': 42, 'siteaccess': 'some=
_siteaccess_name'} ) }}">{{ ez_content_name( content ) }}</a>
{# Linking a regular route #}=20
<a href=3D"{{ url( "some_route_name", {"siteaccess": "some_siteaccess_na=
me"} ) }}">Hello world!</a>=20
namespace Acme\TestBundle\Controller;
use eZ\Bundle\EzPublishCoreBundle\Controller as BaseController;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
class MyController extends BaseController
{
public function fooAction()
{
// ...
$location =3D $this->getRepository()->getLocationService()-&g=
t;loadLocation( 123 );
$locationUrl =3D $this->generateUrl(
$location,
array( 'siteaccess' =3D> 'some_siteaccess_name' ),
UrlGeneratorInterface::ABSOLUTE_PATH
);
$regularRouteUrl =3D $this->generateUrl(
'some_route_name',
array( 'siteaccess' =3D> 'some_siteaccess_name' ),
UrlGeneratorInterface::ABSOLUTE_PATH
);
// ...
}
}=20
Important
url() Twig helper).
URIElement.InvalidArgumentE=
xception will be thrown.Compound\LogicalAnd, all inner matchers Versa=
tileMatcher, it will fail.Compound\LogicalOr, the first inner matcher suc=
ceeding will win.To implement this feature, a new VersatileMatcher was added=
to allow siteaccess matchers to be able to reverse-match.
All=
existing matchers implement this new interface, except the Regexp based ma=
tchers which have been deprecated.
The siteaccess router has been added a matchByName() method=
to reflect this addition. Abstract URLGenerator and DefaultRouter have been updated as well.
Note
SiteAccessRouterInterface.
Landing Page - Known limitation
In eZ Studio's Landing Page you can encounter a 404 error when clicking = a relative link which points to a different siteaccess (if the Content item= being previewed does not exist in the previously used siteaccess). This is= because detecting siteaccesses when navigating in preview is not functiona= l yet. This is a known limitation that is awaiting resolution.
Before 5.4, if you wanted to implement a service needing siteaccess-awar=
e settings (e.g. language settings), you needed to inject the whole C=
onfigResolver (ezpublish.config.resolver) and get the n=
eeded settings from it. This was neither very convenient nor explicit.
The goal of this feature is to allow developers to inject these dynamic = settings explicitly from their service definition (yml, xml, annotation, et= c.).
Static container parameters follow the %<parameter_name>% syntax in Symfony.
Dynamic parameters have the following: $<parameter_name>[; &=
lt;namespace>[; <scope>]]$, default namespace being e=
zsettings, and default scope being the current siteaccess.
This feature also introduces a DynamicSettingParser service tha=
t can be used for adding support of the dynamic settings syntax.
This s=
ervice has ezpublish.config.dynamic_setting.parser for ID and =
implements eZ\Bundle\EzPublishCoreBundle\DependencyInjection\Configur=
ation\SiteAccessAware\DynamicSettingParserInterface.
A few limitations still remain:
config.yml or ezplatform.yml) =
;as they are meant primarily for parameter injection in services. onKernelRequest method (or equivalent).Defining a simple service needing languages parameter (i.e.=
prioritized languages).
Note
Internally, languages parameter is defined as ezsetti=
ngs.<siteaccess_name>.languages, ezsettings being=
eZ internal namespace.
parameters:
acme_test.my_service.class: Acme\TestBundle\MyServiceClass
services:
acme_test.my_service:
class: %acme_test.my_service.class%
arguments: [@ezpublish.config.resolver]
namespace Acme\TestBundle;=20
use eZ\Publish\Core\MVC\ConfigResolverInterface;
class MyServiceClass
{
/**
* Prioritized languages
*
* @var array
*/
private $languages;
public function __construct( ConfigResolverInterface $configResolver )
{
$this->languages =3D $configResolver->getParameter( 'language=
s' );
}
}=20
parameters:
acme_test.my_service.class: Acme\TestBundle\MyServiceClass
services:
acme_test.my_service:
class: %acme_test.my_service.class%
calls:
- [setLanguages, ["$languages$"]]
=20
namespace Acme\TestBundle;
class MyServiceClass
{
/**
* Prioritized languages
*
* @var array
*/
private $languages;
public function setLanguages( array $languages =3D null )
{
$this->languages =3D $languages;
}
}=20
Important: Ensure you always add null as a=
default value, especially if the argument is type-hinted.
parameters:
acme_test.my_service.class: Acme\TestBundle\MyServiceClass
services:
acme_test.my_service:
class: %acme_test.my_service.class%
arguments: ["$languages$"]=20
namespace Acme\TestBundle;
class MyServiceClass
{
/**
* Prioritized languages
*
* @var array
*/
private $languages;
public function __construct( array $languages )
{
$this->languages =3D $languages;
}
}=20
Setter injection for dynamic settings should always be preferred, as it = makes it possible to update your services that depend on them when ConfigRe= solver is updating its scope (e.g. when previewing content in a given SiteA= ccess). However, only one dynamic setting should be injected by set= ter .
Constructor injection will make your service be reset in that ca= se.
parameters:
acme_test.my_service.class: Acme\TestBundle\MyServiceClass
# "acme" is our parameter namespace.
# Null is the default value.
acme.default.some_parameter: ~
acme.ezdemo_site.some_parameter: foo
acme.ezdemo_site_admin.some_parameter: bar
services:
acme_test.my_service:
class: %acme_test.my_service.class%
# The following argument will automatically resolve to the right va=
lue, depending on the current SiteAccess.
# We specify "acme" as the namespace we want to use for parameter r=
esolving.
calls:
- [setSomeParameter, ["$some_parameter;acme$"]]=20
namespace Acme\TestBundle;
class MyServiceClass
{
private $myParameter;
public function setSomeParameter( $myParameter =3D null )
{
// Will be "foo" for ezdemo_site, "bar" for ezdemo_site_admin, or n=
ull if another SiteAccess.
$this->myParameter =3D $myParameter;
}
}=20