Skip to content

siteaccess_matching.md

Latest commit

 

History

History
301 lines (222 loc) · 8.51 KB

siteaccess_matching.md

File metadata and controls

301 lines (222 loc) · 8.51 KB
description page_type
Use SiteAccess matchers to control which site is served when and to which user.
reference

SiteAccess matching

To be usable, every SiteAccess must be matched by one of configured matchers. By default, all SiteAccesses are matched using URIElement: 1.

You can configure SiteAccess matchers under the ibexa.siteaccess.match configuration key:

ibexa:
    siteaccess:
        list: [site, event]
        groups:
            site_group: [site, event]
        default_siteaccess: site
        match:
            Map\URI:
                site: site
                campaign: event

ibexa.siteaccess.match can contain multiple matchers.

The first matcher succeeding always wins, so be careful when using catch-all matchers like URIElement. In the following example, Compound\LogicalAnd is placed before the Map\Host for my.site/corporate to be reachable:

ibexa:
    siteaccess:
        match:
            Compound\LogicalAnd:
                corporate:
                    matchers:
                        Map\URI:
                            corporate: true
                        Map\Host:
                            my.site: true
                    match: corporate
            Map\Host:
                my.site: mysite

If the matcher class doesn't start with a backslash (\), it's relative to Ibexa\Core\MVC\Symfony\SiteAccess\Matcher (for example, Map\URI refers to Ibexa\Core\MVC\Symfony\SiteAccess\Matcher\Map\URI)

You can specify custom matchers by using a fully qualified class name (for example, \My\SiteAccess\Matcher) or a service identifier (for example, @my_matcher_service). In the case of a fully qualified class name, the matching configuration is passed in the constructor. In the case of a service, it must implement Ibexa\Bundle\Core\SiteAccess\Matcher. The matching configuration is passed to setMatchingConfiguration().

Available SiteAccess matchers

URIElement

Maps a URI element to a SiteAccess.

In configuration, provide the element number you want to match (starting from 1).

ibexa:
    siteaccess:
        match:
            URIElement: 2

!!! note

When you use a value > 1, the matcher concatenates the elements with `_`.

Example URI /my_site/company/pages matches SiteAccess my_site_company.

URIText

Matches URI using prefix and suffix sub-strings in the first URI segment.

In configuration, provide the prefix and/or suffix (neither is required).

ibexa:
    siteaccess:
        match:
            URIText:
                prefix: main-
                suffix: /company

Example URI /main-event/company/page matched SiteAccess event.

HostElement

Maps an element in the host name to a SiteAccess.

In configuration, provide the element number you want to match (starting from 1).

ibexa:
    siteaccess:
        match:
            HostElement: 2

Example host name www.example.com matches SiteAccess example.

HostText

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

In configuration, provide the prefix and/or suffix (none are required).

ibexa:
    siteaccess:
        match:
            HostText:
                prefix: www.
                suffix: .com

Example host name www.example.com matches SiteAccess example.

Map\Host

Maps a host name to a SiteAccess.

In configuration, provide a hash map of host/SiteAccess.

ibexa:
    siteaccess:
        match:
            Map\Host:
                www.page.com: event
                adm.another-page.fr: event_admin

Example host name www.page.com matches SiteAccess event.

!!! note

If you encounter problems with the `Map\Host` matcher, make sure that your installation is [properly configured to use token-based authentication](ez_platform_v2.4.md#update-ez-enterprise-v24-to-v242).

Map\URI

Maps a URI to a SiteAccess.

In configuration, provide a hash map of URI/SiteAccess.

ibexa:
    siteaccess:
        match:
            Map\URI:
                campaign: event
                site: site

Example URI /campaign/general/articles matches SiteAccess event.

Map\Port

Maps a port to a SiteAccess.

In configuration, provide a hash map of Port/SiteAccess.

ibexa:
    siteaccess:
        match:
            Map\Port:
                80: event
                8080: site

Example URL http://my_site.com:8080/content matches SiteAccess site.

Ibexa\SiteFactory\SiteAccessMatcher [[% include 'snippets/experience_badge.md' %]] [[% include 'snippets/commerce_badge.md' %]]

Enables the use of Site Factory. Doesn't take any parameters in configuration:

ibexa:
    siteaccess:
        match:
            '@Ibexa\SiteFactory\SiteAccessMatcher': ~

Custom matchers

Beside the built-in matchers, you can also use your own services to match SiteAcceses:

ibexa:
    siteaccess:
        list: [site]
        groups:
            site_group: [site]
        default_siteaccess: site
        match:
            '@App\Matcher\MySiteaccessMatcher': ~

The service must be tagged with ibexa.site_access.matcher and must implement Ibexa\Bundle\Core\SiteAccess\Matcher (and Ibexa\Core\MVC\Symfony\SiteAccess\VersatileMatcher if you want to use compound logical matchers).

Combining SiteAccess matchers

You can combine more than one SiteAccess matcher to match more complex situations, for example:

  • http://example.com/en matches site_en (match host example.com and the en URI element)
  • http://example.com/fr matches site_fr (match host example.com and the fr URI element)
  • http://admin.example.com matches site_admin (match host admin.example.com)

To combine matchers, use compound logical matchers:

  • Compound\LogicalAnd
  • Compound\LogicalOr

Each compound matcher specifies two or more sub-matchers. A rule applies if all the matchers combined with the logical matcher are positive.

To get the result above, you need to combine Map\Host and Map\Uri using LogicalAnd. When both the URI and host match, the SiteAccess configured with match is used.

ibexa:
    siteaccess:
        match:
            Compound\LogicalAnd:
                # You don't need to specify matching values (true is enough).
                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

When using Compound\LogicalAnd, all inner matchers must match. All matchers must implement VersatileMatcher. When using Compound\LogicalOr, the first inner matcher succeeding wins.

Matching by request header

You can define which SiteAccess to use by setting an X-Siteaccess header in your request. This can be useful for REST requests.

In such a case, X-Siteaccess must be the SiteAccess name (for example, site or en).

Matching by environment variable

You can also define which SiteAccess to use directly by using the 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 in web server configuration:

<!--Apache VirtualHost example-->
# This configuration assumes that mod_env is activated
<VirtualHost *:80>
    DocumentRoot "/path/to/ibexa/web/folder"
    ServerName example.com
    ServerAlias www.example.com
    SetEnv EZPUBLISH_SITEACCESS demo_site
</VirtualHost>

!!! tip

You can configure the variable by using the PHP-FPM configuration file.
For more information, see [PHP-FPM documentation](https://www.php.net/manual/en/install.fpm.configuration.php).

!!! note "Precedence"

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

1. Request header
1. Environment variable
1. Configured matchers