Manuel Pichler

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

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 released PHP_Depend 0.9.6, which contains many bug fixes and improvements, but the main feature of this release is behind the scene, I have started to migrate PHP_Depend's internal system from plain Token object to an Abstract Syntax Tree.

• Closed #57: Display caption for abbreviations in overview pyramid, implemented in svn revision #947.
• Closed #80: Store default value for class properties.
• Fixed #81: PHP_Depend does not support comma separated property declarations, fixed in svn revision #916.
• Fixed #82: PHP_Depend does not support comma separated constant definitions, fixed in svn revision #931.
• Closed #83: Make ClassOrInterfaceReference an ASTNode, implemented in svn revision #917.
• Fixed #87: The parent keyword is not accepted as parameter type hint, fixed in svn revision #925.
• Fixed #89: Coupling analyzer reports wrong results, fixed in svn revision #939
• Fixed #90: Coupling analyzer does not handle PHP 5.3 function chains, fixed in svn revision #943.
• Fixed #91: Parser throws an exception when __CLASS__ as default value of an array property, fixed in svn revision #944.
• Closes #92: Use class constants as analyzer identifiers, implemented in svn revision #950.

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

Software metrics are currently on everyone's lips and a frequently discussed topic. There are many conference talks, blog posts and other presentations that talk about software metrics. But to me it seems as if this subject is a closed book for many developers, so I decided to write this little post about a special category of software metrics, the complexity metrics.

Complexity metrics are a theoretical approach to measure the subjective complexity of a software fragment, where the words software fragment stand for a paraphrase for functions, methods, classes and nearly every logical unit that can be found in a software system. The most prevalent procedure to calculate complexity values is static code analysis, where an application parses the raw source code of a project, counts different statements and expressions and packs up the determined results in simple classification numbers. And with this information you already know the main concepts behind most software metrics, classification numbers and counting. As you can see there is no magic behind the scene, the only thing required is a good background knowledge to interpret those values.

The Cyclomatic Complexity Number or short CCN is the oldest complexity metrics. The first time this software metric was mentioned was 1976 by Thomas J. McCabe. This metric counts the available decision paths in a software fragment to determine its complexity. Each decision path starts with one of the conditional statements from the following list, so that it is fairly easy to detect them in existing source code.

• ?
• case
• elseif
• for
• foreach
• if
• while

A look at this list of statements may result in the questions: Is this list wrong, it doesn't list else and default? But it is correct. The assumption is that both statements will contain the defaut execution path of a program which also exists when there are no special cases to capture.

Each decision path gets the value 1 and the sum of all these values represents the Cyclomatic Complexity of the analyzed software fragment. Note that each function and method also counts with a value of 1 With this knowlegde we can now calculate the complexity of the following example code:

Based on the previous definition the Cyclomatic Complexity Number of the example code example is 5. But you may have noticed that this approach does not capture all decision paths that exist. We haven't catched those paths that came from the by the boolean expression || line 6 and && line 8, and the logical or expression in line 25. A variation of the Cyclomatic Complexity Number that also captures those paths is the so called CCN2. The CCN2 is the most widely used variation of this software metrics. Tools like PHPUnit, PMD and Checkstyle report it as Cyclomatic Complexity of an analyzed software fragment.

Now we get a complexity value of 8 when we apply the CCN2 to the previous example, what is a growt of the software's complexity of 60%.

Due to the fact that Cyclomatic Complexity Number was originally invented for procedural programming languages, this definition for the Cyclomatic Complexity Number still misses one element to measure the complexity of an object oriented software system. With the concept of exceptions a software gets additional decision paths for each catch statement used in the source code. While try contains the code for the regular execution code without special cases, similar to else and default statements.

• ?
• &&
• ||
• or
• and
• xor
• case
• catch
• elseif
• for
• foreach
• if
• while

Now that we know what the Cyclomatic Complexity Number is, what can we do with the measured information? We can find the complexity hotspots in a system, for example the top ten artifacts with the highest complexity, but this is only important during an initial analyses phase to get the big picture of an application. For a continuous inspection this information is not so important. A continuous analyses requires thresholds that help to categories calculated values. During the time four values have emerged as good thresholds for the Cyclomatic Complexity Number of a software system.

• A software fragment with a CCN value between 1-4 has low complexity.
• A complexity value between 5-7 is moderate and still easy to understand.
• Everything between 6-10 has a high complexity, while everything greater 10 is very complex and hard to understand.

You may ask, why should I care about the complexity of a software system, where is the value of benefit in this metric?

Mostly the complex parts of an application contain business critical logic. But this complexity has negative impacts on the readability and understandability of source code. Those parts will normally become a maintainence and bug fixing nightmare, because no one knows all the constraints, side effects and what's exactly going on in that part of the software. This situation results in the well known saying "Never touch a running system" which in turn mostly ends in copy&paste programming. The situation can even become more critical when the original author leaves the development team or the company.

Finally a small example how to apply the new knowledge about the Cyclomatic Complexity Number, thresholds and the negative impacts of complex software to an existing development process. The following source listing shows a complex method taken from PHP_Depend's source. This method has a Cyclomatic Complexity Number of 16 and I must admit that the original author needed some time to understand what was going on in this method.

The first thing to do is to make sure that the test suite is good enough to ensure that the required refactorings will not change the public behavior of the component or class. When this is donw and we are sure our that api breaks will be detected by the test suitewe can start to extract logic into separate methods.

The following example shows the result of the refactoring:

The subjective feeling of readability heavily depends on the complexity of control structures, as we can see by a comparison of the original and the refactored version of the method example. The new version with its Cyclomatic Complexity Number of 5 is much easier to read and understand.

This text is the first of two blog posts. The second article will give a short introduction into the NPath Complexity You liked this article and you are interested in this and other quality assurence related topics? - Then you should now order your copy of the Book Quality Assurance in PHP Projects. The book talks about nearly all aspect of quality assurence, with practical tips and expert knowledge contributed by certain PHP professionals.

Today I released PHP_Depend 0.9.5, which contains many bug fixes and improvements. The main features of this release are PHP 5.3 namespace support and a more robust parser that ignores most kinds of syntax errors,

• Closed #2 Support PHP 5.3 namespace syntax, implemented since svn revision #789.
• Closed #61 Catch parser errors and continue processing, implemented in svn revision #880.
• Closed #63 Make ResultPrinter a configurable option, implemented in svn revision #668.
• Fixed #64 The single cache directory causes permission denied on *NIX systems, fixed in svn revision #667.
• Fixed #65 Endless loop for class and interface declarations without body, fixed in svn revision #672.
• Closed #66 Dependency wiring should be done at the end of the parsing process, implemented in svn revision #855.
• Fixed #69 Parser does not handle PHP 5.3 class names in function and method bodies, fixed in svn revision #688.
• Fixed #70 Parser throws an unexpected token exception for closure, fixed in svn revision #726.
• Fixed #71 Parser throws an unexpected token exception for signed default values, fixed in svn revision #740.
• Fixed #73 Inconsistent state when an interface and a class with the same name exists, fixed in svn revision #776.
• Fixed #76 Tokenizer keyword detection is broken, fixed in svn revision #871.

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

Today I released PHP_Depend 0.9.4, which contains many bug fixes and improvements.

• Fixed #92: Handling of types within instanceof-operator fixed.
• Closed #90: Support for single file parsing/analyzing implemented.
• Closed #88: Tokens provide information about the start and end column.
• Closed #87: Support for type definitions within comments implemented.
• Closed #40: Cli debug flag added. PHP_Depend will print additional debug information to STDERR when this cli switch is set.
• The ProjectAwareI and NodeAwareI interfaces extend the AnalyzerI interface, which makes analyzer mocking easier.
• Switch from PHP_Depend specific constants for public, protected, private methods & properties to modifiers compatible with PHP's reflection-extension.
• Support for static modifier for properties&methods and final for methods added.
• Support for class final modifier added.
• Support for chained types like "false|Iterator" or "array(false|Iterator)" in doc comments added.

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

Just now I released PHP_Depend 0.9.3, the primary goal for this release was focused on less memory consumption. A run of PHP_Depend 0.9.2 against eZ Publish took up to 1GB and PHP_Depend 0.9.3 analyzes the same source with a memory limit of 160Mb.

• Fixed #89: The source file is never set for methods, properties and constants.
• Closed #82: Tokenizer cache added, reduces runtime up to 25%.
• Closed #83: Storage layer for node tokens added, reduces memory consumption. .
• Closed #85: TextUI displays the execution time and the memory usage(linux only).
• Code restructured, input filters and iterator moved to package "Input".
• Test suite restructured to reflect the actual project structure.

From now on you will get the latest PHP_Depend version through the new pear channel pear.pdepend.org, for a few weeks I will keep the old pear channel. Enter the following pear commands to upgrade PHP_Depend's channel.

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

Or checkout version 0.9.3 from the PHP_Depend subversion repository.

mapi@arwen ~ $ svn co http://svn.pdepend.org/tags/0.9.3

This is a bug fix release of PHP_Depend. Version 0.9.2 fixes bug #84, which could result in a failure for all PHP versions lower than 5.3.0alpha2.

You can get the latest PHP_Depend version through its PEAR channel pear.xplib.de or as a subversion checkout of the 0.9.2 tag.
Please do not checkout "trunk", it is totally unstable at the moment and I will not provide any support for it.

mapi@arwen ~ $ svn co http://svn.pdepend.org/tags/0.9.2

Just now I released PHP_Depend 0.9.1, the major feature in this new version is an implementation of the NPath Complexity metric, beside that feature the main focus for this release was on performance improvements of the current implementation.

• Closed #21: Support for the NPath Complexity metric.
• Fixed #78: Parser fails for comment in function signature.
• Closed #79: Token objects instead of arrays.

An additional test concept was introduced with the 0.9.* branch of PHP_Depend. Nightly builds test PHP_Depend against a series of open source projects to detect deadlocks like endless loop or similar issues. This procedure is also used to test each release candidate of PHP_Depend. The tested project are:

• Arbit
• eZ Components
• eZ Publish
• PHPUnit
• TYPO3
• Zend Framework

You can get the latest PHP_Depend version through its PEAR channel pear.xplib.de or as a subversion checkout of the 0.9.1 tag.
Please do not checkout "trunk", it is totally unstable at the moment and I will not provide any support for it.

mapi@arwen ~ $ svn co http://svn.pdepend.org/tags/0.9.1

Today I released version 0.9.0 of PHP_Depend. Beside bugfixes this release contains new features like a PHPUnit compatible xml-log.

• Closed #43: An image file name "jdepend" now results in "jdepend.svg" instead of ".svg".
• Closed #42: Print a warning when the analyzed directory does not contain source files.
• Closed #35: Support for custom svg font-family and font-size added.
• Closed #32: Support for function and method parameters added.
• Fixed #30: Approximated Lines Of Code improved.
• Closed #20: Support for class constants implemented.
• Closed #19: PHPUnit compatible logger added.
• Fixed #17: Detect class names in catch statements.
• Fixed #16: Detect class names in instanceof expressions.
• Fixed #46: Default package is broken.

You can get the latest PHP_Depend version through its PEAR channel

mapi@arwen ~ $ pear channel-discover pear.xplib.de
mapi@arwen ~ $ pear install xplib/php_depend

or as a subversion checkout of the 0.9.0 branch or tag.
Please do not checkout "trunk", it is totally unstable at the moment and I will not provide any support for it.

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

Feel free to report issues, bugs or just leave a comment here.

Today I released the stable 0.8.0 version of PHP_Depend.

• Fixed: Endless loop for inline html.
• Fixed: Handle class and interface names case insensitive.
• Fixed: PHP_Depend should print an error if no @package information is available.
• The Logger interface should not force a default ctor-signature.
• Remove Logger <-> XML Config dependency.
• Support for pattern based package filter.
• Tooltip for the Overview Pyramid.
• Add option --bad-documentation.
• Handle internal classes and interfaces.
• Use an SVG-Template for the jdepend chart.
• Introduce a CodeAware interface for loggers.

The previous list was taken from the PHP_Depend issue tracker. Feel free to report issues, bugs or just leave a comment here.

This should be the final beta release for PHP_Depend 0.8.0. Beside some minor bugfixes, it contains a last API change for the log sub component. This change removes constraints to the ctor signature of a logger implementation, which is now part of a separate interface.

The following list shows all changes in this version. A detailed description of all issues can be found in the PHP_Depend issue tracker!

• #29 Tooltip for the Overview Pyramid.
• #34 Support for pattern based package filter.
• #37 Remove Logger - XML Config dependency.
• #38 The Logger interface should not force a default ctor-signature.

As always you can use PHP_Depend's pear channel or its svn repository, to check out this new version. And feel free to discuss and follow the PHP_Depend development on its dedicated mailing list.

The Overview Pyramid is used to visualize a complete software system in a really compact manner. Therefor it collects a set of metrics from the categories Inheritance, Coupling and Size & Complexity, and puts them into relation. The following figure shows the base structure of the Overview Pyramid[ML06].

Base structure of the Overview Pyramid.

Metrics used by the Overview Pyramid

The following three lists contain all the metrics, which the Overview Pyramid uses.

Size and Complexity

The category Size & Complexity contributes the greatest and mostly used set of software metrics.

NOP

The Number Of Packages metric counts the packages within the analyzed software system.

NOC

The Number Of Classes metric counts the declared classes within the analyzed software system.

NOM

The Number Of Methods metric counts all declared methods, which in this context means class methods and simple functions.

LOC

The Lines Of Code metric shows the number of executable source lines within the analyzed software system. To calculate this value PHP_Depend counts all non whitespace lines and all non comment lines.

CYCLO

Cyclomatic complexity is a software metric (measurement). It was developed by Thomas McCabe and is used to measure the complexity of a program. It directly measures the number of linearly independent paths through a program's source code.

Source: Wikipedia

Coupling

This group of metrics informs about the coupling between different program parts in the analyzed application.

CALLS

This metric count the number of distinct function- and method-calls. Distinct means that one and the same method-call within a function- or method-body is only counted once.

FANOUT

The FANOUT provides information on types referenced by classes and interfaces. It only counts those types that are not part of the same Inheritance branch.

Inheritance

Both metrics in this group deal with the use of Inheritance and give a general overview of the use of Inheritance within the analyzed system.

ANDC

The Average Number of Derived Classes metric describes the average of derived classes. In a system of ten classes an ANDC-value of 0.5 means, that every second class is derived from another class.

AHH

The Average Hierarchy Height metric is a average depth of the inheritance hierarchy. In a system of ten classes, a AHH-value of 1 can be interpreted in different ways, for example: Five classes inherit from five other classes within the analyzed application or five classes inherit from a single root class.

Structure of the Overview Pyramid

Now that we know all metrics used for the Overview Pyramid, it is time to replace the placeholders with the measured informations. The figure below shows the filled Overview Pyramid.

The filled Overview Pyramid

In a second step, the previously independent metrics are set into relation. Therefor we calculate the average values of individual value pairs, these computed values provide us with new informations about the distributions within the application.

The following example figure of the Overview Pyramid contains a computed value for the measured LOC and NOM metric which shows us, that in the average each operation has 25 lines of code. This value can be described as very high, especially when you consider that most systems contain a variety of simple operation, like Getter and Setter, in addition to the main application logic.

Computed average values in the Overview Pyramid

To take reasonable conclusions from the computed values one important part is still missing, an adequate set of reference values. Without reference values, that say what values are low, average or high, it is not possible to classify these results. The current version of PHP_Depend supports a single set of reference values, this set was taken from [ML96].

Reference values

With these reference values PHP_Depend can classify the computed results. PHP_Depend uses this information for the generation of colored backgrounds, so that the color already supports the categorization.

The complete Overview Pyramid

The benefit of the Overview Pyramid

Of course, the final question is, which advantages offers the Overview Pyramid?

The Overview Pyramid provides a simple and size indipendent way to get a first impression of a software system, and this without an expensive source code analysis. Thus the Overview Pyramid is an effective tool for a first cost estimate for an unknown system. With the help of this tool and know-how, an experienced developer will quickly get a first impression and will know what can be expected from the analyzed application. And this knowledge could be a good help during the planning phase of a new project.

Bibliography

• Object-Oriented Metrics in Practice
  Using Software Metrics to Characterize, Evaluate, and Improve the Design of Object-Oriented Systems
  Michele Lanza, Radu Marinescu, 2006 © Springer-Verlag Berlin Heidelberg, ISBN 978-3-540-24429-5

If you like commit mails as I do, you can subscribe to the commit mailing list. Simply send an email to commits-join@pdepend.org or register thru the online interface.

If you have any PHP_Depend related questions, tips or suggestions, subscribe to the PHP_Depend user mailing list by mail users-join@pdepend.org or use the online interface.

Enjoy PHP_Depend!

  Manuel