Siteaccess matching is done through eZ\Publish\MVC\SiteAccess\Matcher objects. You can configure this matching and even develop custom matchers.
Configuration
You can configure siteaccess matching in your main app/config/ezplatform.yml:
You need to set several parameters:
- ezpublish.siteaccess.default_siteaccess
- ezpublish.siteaccess.list
- (optional) ezpublish.siteaccess.groups
- ezpublish.siteaccess.match
ezpublish.siteaccess.default_siteaccess is the default siteaccess that will be used if matching was not successful. This ensures that 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 mutualize settings between several siteaccesses and avoid config duplication. Siteaccess groups are treated the same as regular siteaccesses as far as configuration is concerned.
A siteaccess can be part of several groups.
A siteaccess configuration has always precedence on the group configuration.
ezpublish.siteaccess.match holds the matching configuration. 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\SiteAccess\Matcher (e.g. Map\Host will refer to eZ\Publish\MVC\SiteAccess\Matcher\Map\Host)
Every custom matcher can be specified with a fully qualified class name (e.g. \My\SiteAccess\Matcher) or by a service identifier prefixed by @ (e.g. @my_matcher_service).
- In the case of a fully qualified class name, the matching configuration will be passed in the constructor.
- In the case of a service, it must implement
eZ\Bundle\EzPublishCoreBundle\SiteAccess\Matcher. The matching configuration will be passed tosetMatchingConfiguration().
Make sure to type the matcher in correct case. If it is in wrong case like "Uri" instead of "URI," it will happily work on systems like Mac OS X because of case insensitive file system, but will fail when you deploy it to aLlinux server. This is a known artifact of PSR-0 autoloading of PHP classes.
Available matchers
| Name | Description | Configuration | Example |
|---|---|---|---|
URIElement | Maps a URI element to a siteaccess. This is the default matcher used when choosing URI matching in setup wizard. | The element number you want to match (starting from 1). Important: When using a value > 1, it will 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) | URI: Prefix: foo |
HostElement | Maps an element in the host name to a siteaccess. | The element number you want to match (starting from 1). | Host name: Element number: 2 |
HostText | Matches a siteaccess in the host name, using pre and/or post sub-strings. | The prefix and/or suffix (none are required) | Host name: Prefix: www. |
Map\Host | Maps a host name to a siteaccess. | A hash map of host/siteaccess | Map:
Host name: www.example.com Matched siteaccess: foo_front |
Map\URI | Maps a URI to a siteaccess | A hash map of URI/siteaccess | URI: Map:
Matched siteaccess: ezdemo_site |
Map\Port | Maps a port to a siteaccess | A has map of Port/siteaccess | URL: Map:
Matched siteaccess: bar |
Regex\Host | Matches against a regexp and extracts a portion of it | The regexp to match against | Host name: regex: Matched siteaccess: example |
Regex\URI | Matches against a regexp and extracts a portion of it | The regexp to match against | URI: regex: ^/foo(\\w+)bar Matched siteaccess: test |
Compound siteaccess matcher
The Compound siteaccess matcher allows you to combine several matchers together:
- http://example.com/en matches site_en (match on host=example.com and URIElement(1)=en)
- http://example.com/fr matches site_fr (match on host=example.com and URIElement(1)=fr)
- http://admin.example.com matches site_admin (match on host=admin.example.com)
Compound matchers cover the legacy host_uri matching feature.
They are based on logical combinations, or/and, using logical compound matchers:
Compound\LogicalAndCompound\LogicalOr
Each 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 Map\Uri., combined with a LogicalAnd. When both the URI and host match, the siteaccess configured with "match" is used.
Matching by request header
It is possible to define which siteaccess to use by setting an X-Siteaccess header in your request. This can be useful for REST requests.
In such case, X-Siteaccess must be the siteaccess name (e.g. ezdemo_site).
Matching by environment variable
It is also possible to define which siteaccess to use directly via an EZPUBLISH_SITEACCESS environment variable.
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 configuration:
This can also be done via PHP-FPM configuration file, if you use it. See PHP-FPM documentation for more information.
Note about precedence
The precedence order for siteaccess matching is the following (the first matched wins):
- Request header
- Environment variable
- Configured matchers
URILexer and semanticPathinfo
In some cases, after matching a siteaccess, it is neecessary to modify the 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 of the route itself.
The problem is addressed by analyzing this URI and by modifying it when needed through the URILexer interface.
Once modified, the URI is stored in the semanticPathinfo request attribute, and the original pathinfo is not modified.
4 Comments
Philippe Vincent-Royol
Nice work ! Just a question about host/uri match: how could it work with the matcher? it ll be include in ez5 or should we develop it ?
Jérôme Vieilledent
Thanks.
It's a pending task. We will introduce matcher combinators for that. So it will be more powerful
Edit: See Compound SiteAccess matchers.
Joao Inacio
The configuration doc. seems outdated. From what I could tell, It is now set in (and imported from) parameters.yml, using a different structure:
Jérôme Vieilledent
You're right
. I just didn't have time to update the documentation yet 