Configuration

This section explains the configuration model of eZ publish. The default configuration files end with a ".ini" extension and are located in the "/settings" directory. Each file controls the behavior of a specific part of the system. For example, the "content.ini" file controls the behavior of the content engine, the "webdav.ini" file controls the behavior of the WebDAV subsystem, and so on. The main and most important configuration file is called "site.ini". Among other things, it tells eZ publish which database, design, etc. that should be used. The default configuration files contain all the possible directives (with default settings) along with brief explanations. These files files should only be used for reference. In other words, they should never be modified. The "Configuration files" section of the reference chapter contains a comprehensive explanation of the different configuration files and their settings.

File structure

An eZ publish configuration file is divided into blocks, each block contains a collection of settings. The following example shows a part of the main (site.ini) configuration file.

...
# This line contains a comment.
[DatabaseSettings]
Server=localhost
User=allman
Password=qwerty
Socket=disabled
SQLOutput=enabled
 
# This line contains another comment.
[ExtensionSettings]
ActiveExtensions[]=ezdhtml
ActiveExtensions[]=ezpaypal
...

The example above shows two blocks: "DatabaseSettings" and "ExtensionSettings". Each block has several settings which control the behavior of the system. A setting can usually be set to enabled/disabled, a string of text or an array of strings. If the name of a setting ends with a pair of square brackets, it means that the setting accepts an array of values. In the example above, the "ActiveExtensions" setting tells eZ publish to use two different extensions: "ezdhtml" and "paypal". Lines starting with a hash are treated as comments.

Configuration overrides

As pointed out earlier, the default configuration files should never be modified because they will most likely be overwritten by a new set of files during an upgrade. Making a backup will still not be sufficient because the configuration settings change over time. For example, a previous version of the files will not contain settings that were recently added. Because of these issues, custom configuration settings must be placed elsewhere. Global configuration overrides can be placed in the "/settings/override" directory . The settings of the configuration files located in this directory will override the default settings. The name of the configuration files in the override directory must end with one of the following extensions:

.ini.append
.ini.append.php

If an override configuration file exist with both ".ini.append" and ".ini.append.php" extensions, eZ publish will process the one which ends with ".php". Because of possible security issues, the latter (.ini.append.php) should be used; specially if eZ publish is running in a non virtual host environment. The ".php" extension will trick the web server into handling the configuration file as a PHP script. If someone attempts to read it using a browser, the server will not display the contents. Instead, it will attempt to process it as PHP, which again will not produce any output since the configuration settings are commented out (see below). This method makes it more difficult for a hacker to get access to the configuration settings (for example the database password) by attempting to access one of the configuration files from outside. In order for this to work, the contents of the configuration file must be encapsulated by a pair of PHP comment markers: /* and */. The following example shows how an override (for example "test.ini.append.php") should be set up:

<?php /* #?ini charset="iso-8859-1"?
 
# These are my example settings
[ExampleSettings]
ExampleSettingOne=enabled
ExampleSettingTwo=disabled
...
 
*/ ?>

The "charset" directive reveals the character set that was used to construct the ini file (usually ISO-8859-1).