Manuel Pichler

We are proud to announce release 0.10.2 of PHP_Depend. Beside two bug fixes this release implements four new software metrics:

• Efferent Coupling: The number of classes a class depends on.
• Afferent Coupling: The number of classes that depend on a class.
• Number of Public Methods: The public api/interface of a class.
• Coupling Between Objects: The coupling of a class.

A detailed CHANGELOG can be found on the project's download page and a complete, detailed description of the newly implemented software metrics in PHP_Depend's metric catalog.

In this blog post I will describe a useful feature in PHPMD that will simplify your life when it comes to create custom rule sets for PHPMD. PHPMD can be seen as an one level down/low level equivalent to PHP_CodeSniffer. It is a simple command line tool that can be used to check your application's source code for possible bugs, suboptimal or overcomplicated code. The current release of PHPMD ships with three default rule sets. The first set of rules tests the codesize of class, methods and functions. The second rule set contains rules that check your code for unused variables, methods etc. and finally there is a rule set that tests the code against some naming conventions.

Normally when you start using a quality assurance tool, you will not want to use it's default configuration. Sometimes you would like to use only a subset, because the full stack will produce too much noise, or you would like to customize some thresholds, because the factory defaults do not fit to your environment. In this blog post I give a short introduction into PHPMD's rule set syntax and howto to create your own rule set, by reusing parts of the existing default configuration.

If you would like to only pick some of the rules that come with PHPMD and you want to customize some of the predefined thresholds, you can do this by creating your own rule set file that references a custom collection of rules with an individual configuration.

Starting with an empty ruleset.xml file

The simpliest way to start with a new rule set is to copy one of the existing files and remove all the rule-tags from the document body. Otherwise you can use the following example as a template for your own rule set file. You should change the content of the @name attribute and <description /> element to something that describes the purpose of this set.

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0
                     http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="
                     http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        My custom rule set that checks my code...
    </description>
</ruleset>

Adding rule references to the new ruleset.xml file

The first thing we would like to do is to add all unused code rules to the new rule set file. This can simply be done with a <rule /> element that references the entire unused code rule set that comes with PHPMD.

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0
                     http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="
                     http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        My custom rule set that checks my code...
    </description>

    <!-- Import the entire unused code rule set -->
    <rule ref="rulesets/unusedcode.xml" />
</ruleset>

That's it. Now the custom rule set applies all unused code rules against the analyzed source code.

We would also like to use the cyclomatic complexity rule from the existing codesize set in our custom rule set. To achieve this we can reuse the same syntax with a <rule /> element and a @ref attribute.

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0
                     http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="
                     http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        My custom rule set that checks my code...
    </description>

    <!-- Import the entire unused code rule set -->
    <rule ref="rulesets/unusedcode.xml" />

    <!-- Import the entire cyclomatic complexity rule -->
    <rule ref="rulesets/codesize.xml/CyclomaticComplexity" />
</ruleset>

Now that the new rule set uses the cyclomatic complexity rule we would also like to customize some of the rule's properties. First we will increase the rule's priority to the highest possible priority value 1 and we also decrease the threshold when the rule reports a violation. This customization can be done with same xml elements that are used to configure the original rule, so that you can take a look at one of the original rule set file.

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0
                     http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="
                     http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        My custom rule set that checks my code...
    </description>

    <!-- Import the entire unused code rule set -->
    <rule ref="rulesets/unusedcode.xml" />

    <!--
        Import the entire cyclomatic complexity rule and
        customize the rule configuration.
    -->
    <rule ref="rulesets/codesize.xml/CyclomaticComplexity">
        <priority>1</priority>
        <properties>
            <property name="reportLevel" value="5" />
        </properties>
    </rule>
</ruleset>

You should know that PHPMD handles all custom settings additive. This means that PHPMD keeps the original configuration for every setting that isn't customized in a rule reference.

Excluding rules from a rule set

Finally we would like to reuse the naming rule set of PHPMD. But we don't like the two variable naming rules, so that we must exclude them from out rule set file. This exclusion can be achieved by declaring an <exclude /> element within the rule reference. This element has an attribute @name which specifies the name of the excluded rule.

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0
                     http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="
                     http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        My custom rule set that checks my code...
    </description>

    <!-- Import the entire unused code rule set -->
    <rule ref="rulesets/unusedcode.xml" />

    <!--
        Import the entire cyclomatic complexity rule and
        customize the rule configuration.
    -->
    <rule ref="rulesets/codesize.xml/CyclomaticComplexity">
        <priority>1</priority>
        <properties>
            <property name="reportLevel" value="5" />
        </properties>
    </rule>

    <!-- Import entire naming rule set and exclude rules -->
    <rule ref="rulesets/naming.xml">
        <exclude name="ShortVariable" />
        <exclude name="LongVariable" />
    </rule>
</ruleset>

Conclusion

With PHPMD's rule set syntax it is possible to customize all aspects of rules for your own needs and you can reuse every existing rule set xml file in your own set. You should take a look at PHPMD's rule documentation if it happens that you don't know what rules exist or you don't know exactly, which settings are available for one rule, while you create your own set of rules. Another good source of information are the rule set files that are shipped with PHPMD.

You can get the latest PHPMD version from its PEAR channel: pear.phpmd.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear channel-discover pear.phpmd.org
mapi@arwen ~ $ pear install --alldeps phpmd/PHP_PMD-alpha

Or from our github repository:

mapi@arwen ~ $ git clone git://github.com/manuelpichler/phpmd.git

I would be glad if you file a ticket in PHPMD's issue tracker for all issues and/or enhancements you encounter while testing PHPMD.

We are proud to announce the 0.2.3 release of the PHP Mess Detector, a tool that takes source code and performs various tests to calculate various quality aspects from it. The measured values are a good starting point for future improvements. This release contains some new features, for example support for the @SuppressWarnings annotation, that allows you to exclude single methods or complete classes from PHPMD's analyzing process. This annotation can be used to suppress a single rule, a group of rules or PHPMD at all.

/**
 * Suppress all PHPMD warnings for this class.
 *
 * @SuppressWarnings(PHPMD)
 */
class PHPMD_SuppressAll 
{
}

class  PHPMD_SuppressOnMethod
{
    /**
     * Do not warn about the unused parameter $bar.
     *
     * @SuppressWarnings(PHPMD.UnusedFormatParameter)
     */
    public function foo($bar)
    {
    }
}

Beside several bugfixes this release comes with a new set of rules that check the naming of methods, variables etc. against common coding conventions and best practices.

• Fixed #6: PHP Tokenizer required but no error when installing.
• Fixed #7: UnusedLocalVariable ruleset incorrectly flags variables as unused when used inside double quoted string. Fixed in svn revision #187.
• Implemented #9: Add support for "Suppress warnings" annotations. Implemented in svn revision #200.
• Implemented #10: Support for exclude element in rule-set files added. Implemented in svn revision #189.
• Implemented #13: Implement naming rules, e.g. short variables, parameter etc.
• Fixed #14: ExcessivePublicCount rule should utilize PHP_Depend's cis metric. Fixed in svn revision #203.
• Fixed #15: ExcessivePublicCount rule is never used. Fixed in svn revision #202.

You can get the latest PHPMD version from its PEAR channel: pear.phpmd.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear channel-discover pear.phpmd.org
mapi@arwen ~ $ pear install --alldeps phpmd/PHP_PMD-alpha

Or from our github repository:

mapi@arwen ~ $ git clone git://github.com/manuelpichler/phpmd.git

I have just released version 0.9.11 of PHP_Depend. It contains a few bug fixes and improvements for PHP_Depend.

• Fixed #118: Calculation of the Number Of Overwritten Methods is wrong. Fixed in svn revision #1112.
• Fixed #119: Three test cases fail for all PHP versions prior to 5.3. Fixed in svn revision #1114.
• Implemented #121: Parse arguments of the ASTForeachStatement. Implemented in svn revision #1115.
• Critical issue in PHP_Depend's temporary data cache fixed. This bug only occured when running several instances of PHP_Depend in parallel. In this setup the used cache key spl_object_hash() has caused a corrupted cache, because different php process instances have written different data to the same cache file.

As always, you can get the latest PHP_Depend version from its PEAR channel: pear.pdepend.org:

  mapi@arwen ~ $ pear channel-discover pear.pdepend.org
  mapi@arwen ~ $ pear install pdepend/PHP_Depend-beta

Or you can fetch the sources from the subversion reposition:

  mapi@arwen ~ $ svn co http://svn.pdepend.org/branches/0.9.0/

And additionally you can find a repository mirror on github:

  mapi@arwen ~ $ git clone git://github.com/manuelpichler/pdepend.git

I have just released the bug fix version 0.9.10 of PHP_Depend. This release contains several bug fixes and improvements for PHP_Depend.

• Implemented #72__: Add NOAM, NOOM and NOCC metrics. Implemented in svn revision #1084.
• Implemented #74: Make CRAP-index available. Implemented in svn revision #1063.
• Implemented #105: Support for deep search implement. Implemented in svn revision #1078.
• Fixed #106: Filter algorithm is broken for namespaced internal classes. Fixed in svn revision #1039.
• Fixed #110: Duplicate "coupling" directory in test code. Fixed in svn revision #1032.
• Fixed #111: Dynamic Strings are treated as literal strings. Fixed in svn revision #1037.
• Fixed #114: Parsing error caused by complex string expressions fixed. Fixed in svn revision #1068.
• Fixed #115: Summary and PHPUnit Report lists unknown classes. Fixed in svn revision #1101.
• Fixed #116: Returns reference results in parsing error. Fixed in svn revision #1090.
• Performance intensive calculation result cached.
• Test code restructured and improved.
• Concurrency issue for parallel running pdepend instances fixed.

As always, you can get the latest PHP_Depend version from its PEAR channel: pear.pdepend.org:

  mapi@arwen ~ $ pear channel-discover pear.pdepend.org
  mapi@arwen ~ $ pear install pdepend/PHP_Depend-beta

Or you can fetch the sources from the subversion reposition:

  mapi@arwen ~ $ svn co http://svn.pdepend.org/branches/0.9.0/

And additionally you can find a repository mirror on github:

  mapi@arwen ~ $ git clone git://github.com/manuelpichler/pdepend.git

This friday I will give my software metrics introduction talk at the PHP User Group Cologne. The talk covers several aspects of static code analysis. Starting with classic count and complexity metrics, up to modern metrics, which are used for tracking the dependencies and coupling in a modern OO-systems.

In den letzten Jahren findet das Thema Qualitätsicherung immer stärkere Beachtung. Softwaremetriken spielen hierbei eine wichtige Rolle, denn diese statischen Kennzahlen helfen ein Projekt zu überschauen und Schwachstellen frühzeitig aufzudecken. Diese Session gibt einen Überblick über existierende Metriken, Kombinationen und deren Verwendung als Werkzeug zur Qualitätsicherung.

I hope this talk will inspire some of the listerners, how software metrics can be used to improve the quality of their software projects.

The talk will take place at:

• February 5th, 2010
• From 20:00 to 22:00
• Mediapark 5, 50670 Cologne
• (Offices of papaya Software GmbH)

Looking forward to meet you there.

Today I have released version 0.2.0 of the PHP Mess Detector or short PHPMD. PHPMD is a simple, customizable and user friendly frontend application for PHP_Depend. It takes the raw metrics measured by PHP_Depend, compares them with appropriate thresholds and generates a report that lists those software artifacts with potential problems. Such a report can be taken as a basis for human code audits or you can use it as input for an automated build/reporting tool.

Most concepts behind PHPMD are based on those of the well known Java Tool PMD. It uses so called rule set files to organize different sets of rules. There are two purposes that are accomplished by these xml files. The first is to create custom sets of rules which fulfills the projects requirements. The second purpose is the configuration of each rule with thresholds, warning messages and other things. The format of these files is totally borrowed from PMD, so that the reuse existing rule sets in multi language environments should be easy. At the moment PHPMD has two build-in rule sets. One that detects software artifacts with high code size, and the second one detects unused code in your software.

Now lets start with a small How to use it. PHPMD can be called from the command line by typing phpmd, which prints a general help text.

mapi@arwen ~ $ phpmd 
Mandatory arguments:
1) A php source code filename or directory
2) A report format
3) A ruleset filename or a comma-separated string of ...

Optional arguments that may be put after the mandato...
--minimumpriority: rule priority threshold; rules with ...
--reportfile: send report output to a file; default to ...
--extensions: comma-separated string of valid source ...
--ignore: comma-separated string of patterns that are ...

Now let's call PHPMD on its own source, with a simple text report on STDOUT and the codesize ruleset:

mapi@arwen ~ $ phpmd ~/phpmd/source text codesize

/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:66 \
  This class has too many methods, consider refactoring it.
/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:267 \
  The method _parseSingleRuleNode() has a Cyclomatic \
  Complexity of 11.
/home/mapi/phpmd/source/PHP/PMD/RuleSetFactory.php:326 \
  The method _parseRuleReferenceNode() has a Cyclomatic \
  Complexity of 10.

The --reportfile option can be used, to redirect the report output into a file. So let us repeat the previous example that writes the report into a file, additionally uses the unusedcode rule and changes the format from text to xml.

mapi@arwen ~ $ phpmd ~/phpmd/source xml codesize,unusedcode \
  --reportfile ~/pmd.xml
mapi@arwen ~ $ cat ~/pmd.xml 
<?xml version="1.0" encoding="UTF-8" ?>
<pmd version="@package_version@" timestamp="...">
  <file name=".../source/PHP/PMD/RuleSetFactory.php">
    <violation beginline="66" endline="417" rule="TooManyMet ...>
      This class has too many methods, consider refactoring it.
    </violation>
    <violation beginline="267" endline="315" rule="Cyclomati ...>
      Method _parseSingleRule() has a Cyclomatic Complexity of 11.
    </violation>
    <violation beginline="326" endline="367" rule="Cyclomati ...>
      Method _parseRuleReference() has a Cyclomatic Complexity of 10.
    </violation>
  </file>
</pmd>

This xml file is compatible with those files generated by PMD and PHPUnit's deprecated --log-pmd option. So that it should be no problem to use this files in existing environments like Hudson, CruiseControl or Sonar.

Currently PHPMD supports the following three different report formats: Text, HTML and XML. And it has the build-in rule sets: codesize and unusedcode.

You can get the latest PHPMD version from its PEAR channel: pear.phpmd.org

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear channel-discover pear.phpmd.org
mapi@arwen ~ $ pear install --alldeps phpmd/PHP_PMD-alpha

Today I have released the first version of the staticReflection component. This component parses the source files of a project to provide reflection information identical to that provided by PHP's build in API, without loading the class declaration into the PHP runtime context. Due to the API compatibility the staticReflection component can simply be used as a drop-in replacement for the reflection extension.

A few weeks ago I started just another script that utilized the tokenizer extension to extract some information from source code files. At that point I thought that the time had come to realize a project that was on my todo for a very long time. And here is the result of the first iteration, a userland reflection implementation that is api compatible with PHP's internal reflection extension. Beside the source parser and the reflection ast this component provides a unified interface to both reflection versions, which makes it easy to switch between different implementations.

As a first use case for this component I have choosen autoload files, as they are used by the eZ Components. The generation of those files is really easy, simply parse a directory with source files and dump the result into a file.

<?php
use org\pdepend\reflection\Autoloader;
use org\pdepend\reflection\ReflectionSession;

// Include the bundled autoloader
include_once 'staticReflection/Autoloader.php';

// Register the autoload function
spl_autoload_register( array( new Autoloader(), 'autoload' ) );

// Create a new session
$session = new ReflectionSession();

// Create a directory query
$query = $session->createDirectoryQuery(  );

$autoload = array();
foreach ( $query->find( __DIR__ . '/../../source/' ) as $class )
{
    $autoload[$class->getName()] = $class->getFileName();
}

var_export( $autoload ); 

You can also use the static reflection implementation to analyze different versions of the same class in the same process, which is not possible with the build-in reflection API, because you cannot load multiple classes with the same name into the current runtime context.

Beside parsing of a given directory or file the staticReflection component also supports direct access to a concrete class or interface through the name. Therefor it uses so called source resolvers, that perform a mapping between class names and the associated source files. The current release has two build-in resolvers, one using autoload arrays as they are used by the eZ Components and the other one uses the PEAR naming conventions and the configured include_paths to determine the source file for a given class name. The following example illustrates the usage of the PEAR source resolver.

<?php
use org\pdepend\reflection\Autoloader;
use org\pdepend\reflection\ReflectionSession;
use org\pdepend\reflection\factories\StaticReflectionClassFactory;
use org\pdepend\reflection\resolvers\PearNamingResolver;

include_once 'staticReflection/Autoloader.php';

spl_autoload_register( array( new Autoloader(), 'autoload' ) );

$session = ReflectionSession::createStaticSession(
    new PearNamingResolver()
);

$class = $session->getClass( 'PEAR_Frontend' );
echo '- ', $class->getName(), PHP_EOL,
     '    ', $class->getFileName(), PHP_EOL;

This concept makes the component extremly flexible, because you can write your own source resolver that fulfills the requirements for your application.

Beside the source resolver concept the ReflectionSession can also be configured with a custom stack of ReflectionClassFactory objects that are used to retrieve a reflection class instance for a given class/interface name. To minimize the configuration overhead for common use cases the ReflectionSession class provides three build-in factory methods that create default session configurations for you:

• ReflectionSession::createDefaultSession( SourceResolver ): This session configuration uses three different backends. First it asks the native backend for a reflection class. When this backend cannot handle the request the static reflection factory is asked for a matching class. Finally this configuration uses the null backend, which always returns an empty placeholder reflection class.
  
  
• ReflectionSession::createStaticSession( SourceResolver ): This session setup first asks the static reflection implementation for a matching reflection class and falls back to the null backend when no matching class exists.
  
  
• ReflectionSession::createInternalSession(): This factory method creates a session setup that is a simple wrapper around PHP's internal reflection api.
  
  

But you can always build your own session configuration with a custom factory stack, by calling the ReflectionSession::addClassFactory() method on the session instance.

<?php
use org\pdepend\reflection\Autoloader;
use org\pdepend\reflection\ReflectionSession;

include_once 'staticReflection/Autoloader.php';

spl_autoload_register( array( new Autoloader(), 'autoload' ) );

$session = new ReflectionSession();
$session->addClassFactory( new MyFooFactory() );
$session->addClassFactory( new MyBarFactory() );

So how can you use this cool component in your application? This is really simple, just replace all ReflectionClass instantiations with the following code:

<?php
// ...
// Previous instantiation
// $ref = new ReflectionClass( 'Foo_Bar_Baz' );

// New cool solution
$ref = ReflectionSessionInstance::get()->getClass( 'Foo_Bar_Baz' );

And add the following code to your bootstrap file:

<?php
// ...
ReflectionSessionInstance::set(
    ReflectionSession::createInternalSession()
);

Finally some words to the requirements and the installation of this component. This component requires PHP in a version greater or equal 5.3.0. For installation you can use PHP_Depend's PEAR channel:

mapi@arwen ~ $ pear channel-discover pear.pdepend.org
mapi@arwen ~ $ pear install pdepend/staticReflection-alpha

or you can download the latest version from the staticReflection svn respository:

mapi@arwen ~ $ svn co http://svn.reflection.pdepend.org/trunk \
                      staticReflection

Feel free to test this component and file bug-reports and/or feature-requests in the project issue tracker.