Navigation
eZ Documentation Center
 

This is outdated documentation made for eZ Publish Platform 5.2. It is being moved into the eZ Publish 5.x documentation, so please go there for most up-to-date documentation.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of Contents

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 ezpublish/config/ezpublish.yml :

Code Block
languagenone
titleezpublish.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

 

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 are member of. This is useful when you want to mutualize settings between several siteaccesses and avoid config duplication. Siteaccess groups are considered as regular siteaccesses as far as configuration is concerned.

Tip

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)

Tip

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 to setMatchingConfiguration().

Available matchers

NameDescriptionConfigurationExample
URIElementMaps 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).

Code Block
ezpublish:
    siteaccess:
        match:
            URIElement: 1

Important: When using a value > 1,
it will concatenate the elements with _

URI: /ezdemo_site/foo/bar

Element number: 1
Matched siteaccess: ezdemo_site

Element number: 2
Matched siteaccess: ezdemo_site_foo 

URITextMatches URI using pre and/or post sub-strings
in the first URI segment

The prefix and/or suffix (none are required)

Code Block
ezpublish:
    siteaccess:
        match:
            URIText:
                prefix: foo
                suffix: bar

URI: /footestbar/my/content

Prefix: foo
Suffix: bar
Matched siteaccess: test 

HostElementMaps an element in the host name to a siteaccess.

The element number you want to match (starting from 1).

Code Block
ezpublish:
    siteaccess:
        match:
            HostElement: 2

Host name: www.example.com

Element number: 2
Matched siteaccess: example 

HostTextMatches a siteaccess in the host name,
using pre and/or post sub-strings.

The prefix and/or suffix (none are required)

Code Block
ezpublish:
    siteaccess:
        match:
            HostText:
                prefix: www.
                suffix: .com

Host name: www.foo.com

Prefix: www.
Suffix: .com
Matched siteaccess: foo 

Map\HostMaps a host name to a siteaccess.

A hash map of host/siteaccess

Code Block
ezpublish:
    siteaccess:
        match:
            Map\Host:
                www.foo.com: foo_front
                adm.foo.com: foo_admin
                www.stuff.fr: bar_front
                adm.stuff.fr: bar_admin
Map:
  • www.foo.com => foo_front
  • admin.foo.com => foo_admin 

Host name: www.example.com

Matched siteaccess: foo_front

Map\URIMaps a URI to a siteaccess

A hash map of URI/siteaccess

Code Block
ezpublish:
    siteaccess:
        match:
            Map\URI:
                something: ezdemo_site
                foobar: ezdemo_site_admin

URI: /something/my/content

Map:

  • something => ezdemo_site
  • foobar => ezdemo_site_admin

Matched siteaccess: ezdemo_site

Map\PortMaps a port to a siteaccess

A has map of Port/siteaccess

Code Block
ezpublish:
    siteaccess:
        match:
            Match\Port:
                80: foo
                8080: bar

URL: http://ezpublish.dev:8080/my/content

Map:

  • 80: foo
  • 8080: bar

Matched siteaccess: bar

Regex\HostMatches against a regexp and extract a portion of it

The regexp to match against
and the captured element to use

Code Block
ezpublish:
    siteaccess:
        match:
            Regex\Host:
                regex: "^(\\w+_sa)$"
                # Default is 1
                itemNumber: 1

Host name: example_sa

regex: ^(\\w+)_sa$
itemNumber: 1

Matched siteaccess: example

Regex\URIMatches against a regexp and extract a portion of it

The regexp to match against
and the captured element to use

Code Block
ezpublish:
    siteaccess:
        match:
            Regex\URI:
                regex: "^/foo(\\w+)bar"
                # Default is 1
                itemNumber: 1


URI: /footestbar/something

regex: ^/foo(\\w+)bar
itemNumber: 1

Matched siteaccess: test 

 

Compound siteaccess matcher

The Compound siteaccess matcher allows to combine several matchers together, this can most commonly be used to performed a legacy host_uri match.

For that, the following matchers can be used in your siteaccess match:

  • Compound\LogicalAnd
  • Compound\LogicalOr

Code Block
languagenone
titleezpublish.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
            # The following mimics host_uri for 2 different configuration.
            Compound\LogicalAnd:
                my_compound_rule_1:
                    # Nested matchers, with their configuration.
                    # No need to precise their matching values (true will suffice).
                    matchers:
                        Map\URI:
                            the_front: true
                        Map\Host:
                            ezpublish.dev: true
                    # The siteaccess to match in the end
                    match: ezdemo_site 
                my_compound_rule_2:
                    matchers:
                        Map\URI:
                            the_admin: true
                        Map\Host:
                            ezpublish.dev: true
                    match: ezdemo_site_admin
            # Matching hosts as host: siteaccess
            Map\Host:
                ezpublish.dev: ezdemo_site
                admin.ezpublish.dev: ezdemo_site_admin

Matching by request header

It is possible to define which siteaccess to use by setting a 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:

Code Block
languagenone
titleApache VirtualHost example
# 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>
Tip

This can also be done via PHP-FPM configuration file, if you use it. See PHP-FPM documentation for more information.

Info
titleNote about precedence

 The precedence order for siteaccess matching is the following (the first matched wins):

  1. Request header
  2. Environment variable
  3. 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.

Code Block
languagephp
titleURILexer interface
/**
 * Interface for SiteAccess matchers that need to alter the URI after matching.
 * This is useful when you have the siteaccess in the URI like "/<siteaccessName>/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 have the siteaccess part back in the URI.
     *
     * @param string $linkUri
     * @return string The modified link URI
     */
    public function analyseLink( $linkUri );
}

Once modified, the URI is stored in the semanticPathinfo request attribute, and the original pathinfo is not modified.