Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

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="utf-8"?
 
# 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 UTF-8).

Balazs Halasy (14/09/2010 10:27 am)

Geir Arne Waaler (28/09/2010 7:36 am)


Comments

  • Override means override?

    I mean, ezpublish takes the default configuration file and if exists override it with the properties found in the corresponding override file.
    We only need to override the properties we want to change, not copy the whole file in the overide directory and change some properties.
    It's a question.
    • Re: Override means override?

      Yes, you only need the properties you want to change in your override files, EZ will take the other ones from the default files (or the global override files).
  • Ini array handling

    It's easy to test on your own, but still could be helpful for some people to know, that:
    # This declares the array (and empties it, if it had been declared before)!
    ActiveExtensions[]
    # This pushes an empty string as a value of the array!
    ActiveExtensions[]=