Agavi's standard configuration file format is XML, but you can use any format you like for your custom files (you'll probably have to write a parser, though). Each configuration file may also have a parent, which is also read during compilation, and the two files get merged together, with the child file overwriting settings from the parent. Of course, the parent file may again reference a parent and so on, which is an excellent way to easily enforce common settings etc across projects.

All configuration files are compiled into a very efficient format by their Configuration Handler to maximize performance. Once this compilation has occured, the compiled version will be used until the configuration file is modified. Then, the compilation will occur again. If Agavi is running in debug mode, configuration files are always re-compiled on each request.

Each configuration file should have an XML prolog. The default encoding is UTF-8, but you can set any encoding you like; Agavi will then translate encodings during compilation. Note that this requires the iconv extension, unless you're using ISO-8859-1, which can be handled without the help of iconv.

The root element of each configuration file is <configurations>. It may have an optional attribute called "parent" which can be used to specify the parent configuration file. This root element must contain at least one <configuration> element, which then contains the actual configuration directives.

The reason why <configurations> contains <configuration> elements is that a <configuration> block can be specific to an environment, a context, or both. To achieve this, pass a space separated list of names to the "enviroment" and/or "context" attributes of the tag. This way, you can write very fine-grained config files to change behavior according to the situation. For example, the basic settings.xml file has different settings per environment (example simplified):

<configurations>
  <configuration>
    <settings>
      <setting name="debug">false</setting>
    </settings>
  </configuration>
  <configuration environment="development">
    <settings>
      <setting name="debug">true</setting>
    </settings>
  </configuration>
</configurations>

In this example, debug is always disabled unless the environment is set to "development". Note that environments and contexts do not have to be declared anywhere. Bootstrapping an environment or getting a context instance "activates" the environment or context. If you have declared settings specific to them, they'll be used. If not, the "global" settings (i.e. those in <configuration> blocks without further attributes) take effect.

Environment-specific settings overwrite generic ones, context-specific settings overwrite environment-specific ones, and environment- and context-specific settings overwrite all of the before.

You'll also soon notice that for each element that may occur multiple times, the parent element is the plural form of the name. <route> elements sit inside <routes>, <mouse> elements inside <mice> and so on.

Also, you can use a <sandbox> element inside <configurations> to store XML chunks for easier inclusion in the local document using XInclude.

Many tags in configuration files accept a <parameters> block as the child element which is usually used to specify initialization arguments to the respective resource. Each <parameter> inside the <parameters> container has a name, specified via the attribute "name", and a value. This value can, however, again be a <parameters> block. This inner block often does not need name attributes for the <parameter> elements, because it usually is simply a list of values for the parent <parameter>. Here's an example:

<parameters>
  <parameter name="firstparam">a value goes here</parameter>
  <parameter name="secondparam">
    <parameters>
      <parameter>foo</parameter>
      <parameter>bar</parameter>
    </parameters>
  </parameter>
</parameters>

Parameter blocks, but also many other attributes and values may contain the name of a configuration directive, wrapped in percent signs.

The following parameter will contain the path name of the project's app dir followed by "/fubar", because the directive is expanded before assignment:

<parameter name="path">%core.app_dir%/fubar</parameter>

Also, in parameter blocks and sometimes in other locations, boolean expressions are expanded to actual boolean values:

<parameter name="use_logging">false</parameter>

Will assign boolean false to the parameter "use_logging".