Example of a setup with two siteaccesses.
A single eZ Publish installation is capable of hosting multiple sites by making use of something called the siteaccess system. This system makes it possible to use different configuration settings based on a set of rules. The rules control which group of settings that should be used in a particular case. The siteaccess rules must be specified in the global override for the site.ini configuration file ("/settings/override/site.ini.append.php").
A collection of configuration settings is called a siteaccess. When a siteaccess is in use, the default configuration settings will be overridden by the settings that are defined for the siteaccess. Among other things, a siteaccess dictates which database, design and var directory that should be used (these are sometime referred to as "resources"). By making use of different siteaccesses, it is possible to combine different content and designs. A typical eZ Publish site consists of two siteaccesses: a public interface for visitors and a restricted interface for administrators. Both siteaccesses use the same content (same database and same var directory) but they use different designs. While the administration siteaccess would most likely use the built in administration design, the public siteaccess would use a custom design. The following illustration shows this scenario.
Example of a setup with two siteaccesses.
A siteaccess is nothing more than a set of configuration files that override the default settings when the siteaccess is used. A single eZ Publish installation can virtually host an unlimited number of sites by the way of siteaccesses. The configuration settings for a siteaccess are located inside a dedicated subdirectory within the "/settings/siteaccess" directory. The name of the subdirectory is the actual name of the siteaccess.
Rules for siteaccess names
eZ Publish has a set of characters that are allowed for a siteaccess name. They are the alphanumerical characters (the [a-z], [A-Z] and [0-9] ranges), and the "_" (underscore).
These are the simple rules for characters converting:
Examples: You can have an http://example.org/ and an http://admin.example.org/sites, where the hostname is used for matching the SA. In this case, example.org will be changed to example_org and admin.example.org to admin_example_org. Another example is an URL with a space: http://example.com/main area/ which would lead to SA "main_area".
The rules above are only valid for the element URIMatchType option.
Note: If you don't want the transformation to be done, you can use URIMatchType=map instead.
The following illustration shows a setup with two siteaccesses: admin and public.
Siteaccess directory example.
When a siteaccess is in use, eZ Publish reads the configuration files using the following sequence:
0 - Default configuration settings - /settings/*.ini?
1 - Active extension siteaccesses - /extension/my_extension/settings/siteaccess/my_site/*.ini.append.php
2 - Siteaccesses - /settings/siteaccess/my_site/*.ini.append.php?
3 - Active extensions - /extension/my_extension/settings/*.ini[.append.php]?
4 - Global overrides - /settings/override/*.ini.append.php
In other words, eZ Publish will first read the default configuration settings. Secondly it will read my_site/*.ini.append.php to find the siteaccesses for the active extensions for the installation. Then it will determine which siteaccess to use based on the rules that are defined in the global override for "site.ini" ("/settings/override/site.ini.append.php"). When it knows which siteaccess to use, it will go into the directory of that siteaccess and read the configuration files that belong to that siteaccess. Next it will go into the configuration file for the active extensions and read the configuration files for the active extensions. The settings of the siteaccess will override the default configuration settings.
For example, if the siteaccess uses a database called "Amiga", the system will see this and automatically use the specified database when an incoming request is processed. Finally, eZ Publish reads the configuration files in the global override directory. The settings in the global override directory will override all other settings. In other words, if a database called "CD32" is specified in the global override for "site.ini" then eZ Publish will attempt to use that database regardless of what is specified in the siteaccess settings. If a setting is not overridden by either the siteaccess or from within a global override then the default setting will be used. The default settings are set by the ini files located in the "/settings" directory.
The following figure illustrates how the system reads the configuration files using the "site.ini" file as an example. As already mentioned, settings placed in the override files will be used instead of the default ones.
Configuration override example.
This applies for Online Editor and other extensions:
if a configuration array is initialized in "extension/<extension_name>/settings/<ini_file>" and you want to insert a new value into this array:
1. Do not edit "extension/<extension_name>/settings/<ini_file>", because it will be overwritten next time when you upgrade the extension.
2. Do not create "extension/<extension_name>/settings/siteaccess/<siteaccess_name>/<ini_file>", because it will be overridden by "extension/<extension_name>/settings/<ini_file>".
3. Do not create or edit "settings/siteaccess/<siteaccess_name>/<ini_file>", because it will be overriden by "extension/<extension_name>/settings/<ini_file>".
4. To affect all siteaccesses where <extension_name> is used, specify new value in "settings/override/<ini_file>".
5. To only affect a certain siteaccess, you need to use the following workaround:
- create a new custom extension specially for these settings: "extension/<custom_extension>/"
- specify new value in "extension/<custom_extension>/settings/<ini_file>"
- enable the custom extension for the target siteaccess by adding
ActiveAccessExtensions[]=<custom_extension>
to "settings/siteaccess/<siteaccess_name>/site.ini.append.php"
- make sure the configuration array is not re-initialized in "settings/override/<ini_file>" (if exists).
Note: The name of <ini_file> here should always contain either ".append" or ".append.php" in the end. The only exception are default configuration files (for example "settings/design.ini" or "extension/ezoe/settings/ezoe.ini").
Note: A non technical description of a site access is to view it as a "Content Channel": a Content Channel refers to a way the user of an eZ Publish installation can access the content, this encompasses
- all “front end” site accesses like a website, or a mobile version of the website,
- all “back end “ site accesses like the administration interface(s)
- all automated content access interfaces like Application Programmers Interfaces (APIs)
‘ Translated versions of a site are not counted as additional site accesses