PHP Depend - Software Metrics for PHP

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:

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.

~ $ 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.

~ $ 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>

Command Line

Reports

By Manuel Pichler licensed under BSD-3-Clause