Configuration
~~~~~~~~~~~~~

:Author:       Manuel Pichler
:Copyright:    All rights reserved
:Description:  This document describes the configuration component of
               PHP_Depend. The configuration system allows to customize
               several aspects of PHP_Depend through a simple xml file.
:Keywords:     Configuration, XML, XML-Schema, PHP_Depend, Command-Line

Newer versions of PHP_Depend provide a flexible and easy to use configuration
file. This file can be used to tune several aspects of PHP_Depend, that were
normally hard and complicated to configure with pure command line options.

The format has changed in version 2.0 and is now embedded into the Symfony
DependencyInjection Container configuration. Besides overwriting some settings,
you are now able to overwrite many of the internal PDepend services with your
own implementations and extend the parsing process with generators and
analyzers. You can find the old format in the History section below.

Base configuration file
=======================

The minimum configuration file consists of a root element with some namespaces
but without any child elements or attributes, because all settings are optional. ::

  <?xml version="1.0" ?>
  <symfony:container xmlns:symfony="http://symfony.com/schema/dic/services"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://pdepend.org/schema/dic/pdepend"
      xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd" />

Rhe `XML schema`__ for the configuration
file is used in order to get automatic validation and auto-completion in your
development environment.

Elements
========

Image Convert
-------------

The ``<image-convert>`` element is a container for all configuration settings
available for the image convert component. It is used by PHP_Depend to render
the different graphical reports like the `Overview Pyramid`__ or the the
*Abstraction & Instability* chart. ::

  <?xml version="1.0" ?>
  <symfony:container xmlns:symfony="http://symfony.com/schema/dic/services"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://pdepend.org/schema/dic/pdepend"
      xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd" />
      <config>
          <image-convert>
              <font-family>Luxi Sans</font-family>
              <font-size>42</font-size>
          </image-convert>
      </config>
  </symfony:container>

At the moment you can only customize the font-size and the font-family that
were used in the generated graphics.

fontFamily
``````````

The ``<font-family>`` element can be used to specify a custom font-family that
should be used for all text elements rendered by PHP_Depend. This element
accepts any valid font-family identifier, as they are used to specify a
font-family in a css- or svg-file. ::

  <image-convert>
      <font-family>Luxi Sans</font-family>
  </image-convert>

Or you can specify a list of font-families: ::

  <image-convert>
      <font-family>Luxi Sans, Verdana, sans-serif</font-family>
  </image-convert>

fontSize
````````

The ``<font-size>`` element can be used to specify a new base font-size for all
charts generated by PHP_Depend. This base font-size will be used by the image
convert component to recalculate all font sizes used within a chart. This
element only accepts data of type *int*. ::

  <image-convert>
      <font-size>42</font-size>
  </image-convert>

cache
-----

Within the ``<cache>`` container element you can configure the cache backend
that will be used by PHP_Depend. The used cache backend can have a great
impact on PHP_Depend's overall performance, memory consumption and diskspace
usage. While the file based cache promises a better performance on consecutive
calls, it can require a large amount of diskspace. In contrast, the memory
based cache doesn't allocate any diskspace, but it normally requires muc
more memory and it forces the PHP_Depend to parse the whole source on every
call. ::

  <?xml version="1.0" ?>
  <symfony:container xmlns:symfony="http://symfony.com/schema/dic/services"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://pdepend.org/schema/dic/pdepend"
      xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd" />
      <config>
          <cache>
              <driver>file</driver>
              <location>/var/run/pdepend</location>
          </cache>
      </config>
  </symfony:container>

driver
``````

The ``<driver>`` element can be used to define the cache backend for
PHP_Depend. At the moment this element only accepts two predefined values
as content:

- ``file``
- ``memory``

The cache driver must be specified as cdata of the ``<driver>`` element. ::

  <cache>
      <driver>file</driver>
  </cache>

The default driver used by PHP_Depend is ``file``.

location
````````

The ``<location>`` element can be used to define a custom location for the
cache files generated by PHP_Depend. As this statement already implies, the
``<location>`` element is only used by the file system based cache and will
be ignored for the memory driver. ::

  <cache>
      <location>/tmp/pdepend/cache</location>
  </cache>

The default cache location under linux/unix systems is ``$HOME + "/.pdepend"``
and under windows ``$HOMEDRIVE + $HOMEPATH + "/.pdepend"``.

ttl
````````

The ``<ttl>`` element can be used to define a custom ttl in seconds for the
cache files generated by PHP_Depend. As this statement already implies, the
``<ttl>`` element is only used by the file system based cache and will
be ignored for the memory driver. ::

  <cache>
      <ttl>3600</location>
  </cache>

The default cache ttl is ``2592000`` = 30 days.

Using the configuration file
============================

There are two ways how the PHP_Depend configuration file can be specified.
The first style is to declare the configuration file explicit, by using the
command line option ``--configuration``.

.. class:: shell

::

  ~ $ pdepend --configuration=my.config.xml

The second style/concept to specify PHP_Depend's configuration file was
adapted from `PHPUnit`__, where you can put an xml file named after the
tool(so ``phpunit.xml`` in the case of PHPUnit and ``pdepend.xml`` in the
case of PHP_Depend) into the current working directory. This file will
then be read and parsed automatically by PHP_Depend.

.. class:: shell

::

  ~ $ ls -l
  drwxrwxr-x  8 4096 Nov 24 11:05 build
  drwxrwxr-x  8 4096 Nov 24 11:05 src
  -rwxr--r--  1  806 Oct 19 15:07 pdepend.xml
  ~ $ pdepend --jdepend-xml=build/logs/jdepend.xml src

In this case PHP_Depend parse the configuration settings defined in the
```pdepend.xml`` file, right before it starts to parse the source.

Beside this configuration file you can also put a second file named
``pdepend.xml.dist`` into the current working directory. The purpose of
the ``*.dist`` is to provide a project with factory settings for PHP_Depend,
while the ``*.xml`` is reserved for modifications in each checkout.

PHP_Depend reads both configuration files additive. This means it first
reads the ``pdepend.xml.dist`` and overwrites the default values with those
found in the xml file. Then it reads the ``pdepend.xml`` file and only
overwrites those settings that were defined in this file.

History
=======

The command line option to specify a xml configuration file already exists
for a long time in PHP_Depend, but the configuration file wasn't really in
use until version 0.10.0. Since this release we have started to provide an
`XML-Schema`__ for the configuration file and we moved several command line
options or previously hard-coded-switches into the xml configuration file.

Starting with 2.0 the format was changed to allow integration in the
Symfony Dependency Injection Container. For legacy reasons the old
format is documented here ::

    <?xml version="1.0" ?>
    <configuration>
        <imageConvert>
            <fontFamily>Luxi Sans</fontFamily>
            <fontSize>42</fontFamily>
        </imageConvert>
        <cache>
            <driver>file</driver>
            <location>/tmp</location>
        </cache>
    </configuration>

__ http://pdepend.org/schema/1.0/configuration.xsd
__ /documentation/handbook/reports/overview-pyramid.html
__ http://www.phpunit.de/manual/3.5/en/index.html
__ http://pdepend.org/schema/1.0/configuration.xsd

.. class:: prev

`Command Line`__

.. class:: next

`Reports`__

__ /documentation/handbook/command-line.html
__ /documentation/handbook/reports.html
