planet-php

In this blog post I will give you a brief introduction into the Coupling Between Objects metric, that is one of the metrics calculated by the static code analysis tool PHP_Depend.

The Coupling Between Objects or CBO metric was originally defined by Chidamber & Kemerer in their IEEE paper "A Metrics Suite for Object Oriented Design" [1]. This software metric represents the number of other types a class or interface is coupled to. The CBO metric is calculated for classes and interfaces. It counts the unique number of reference types that occur through method calls, method parameters, return types, thrown exceptions and accessed fields. But there is an exception for types that are either a subtype or supertype of the given class, because these types are not included in the calculated CBO value.

Excessive coupled classes prevent reuse of existing components and they are damaging for a modular, encapsulated software design. To improve the modularity of a software the inter coupling between different classes should be kept to a minimum. Beside reusability a high coupling has a second drawback, a class that is coupled to other classes is sensitive to changes in that classes and as a result it becomes more difficult to maintain and gets more error-prone. Additionally it is harder to test a heavly coupled class in isolation and it is harder to understand such a class. Therefore you should keep the number of dependencies at a minimum.

Thresholds

Based on their research Sahraoui, Godin and Miceli [2] suggest a maximum CBO value of 14, because higher values have negative impacts on several quality aspects of a class, which includes the maintainability, stability and understandability.

See also

Efferent Coupling:

Efferent Coupling or CE is a different name for the same metric, that is frequently used in the literatur.

Afferent Coupling:

The Afferent Coupling or CA is a metric that calculates the reverse coupling of a class.

Bibliography

[1]

http://www.iiitd.ac.in/PhD2010/papers/SW_Paper2.pdf

IEEE Transactions on Software Engineering; A Metrics Suite for Object Oriented Design; Chidamber & Kemerer, 1994

[2]

http://www.iro.umontreal.ca/~sahraouh/papers/ICSM00.pdf

Software Maintenance, 2000. Proceedings. International Conference; Can metrics help to bridge the gap between the improvement of OO design quality and its automation?; Sahraoui, Godin, Miceli; 2000

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.

This blog post will give you a brief introduction into the Class Interface Size metric, as it is calculated by the static code analysis tool PHP_Depend.

The Class Interface Size or CIS metric is measure of the public services that a class provides. This metric was orginally defined in the QMOOD model [1] by Bansiya & Davis.

The orginal version of the CIS metric was defined as the number of public methods that a class provides. Each of these methods can be seen as a service where surrounding application can send messages to or receive messages from a class.

CIS = public(NOM)

A newer variant of the CIS metric also includes the public attributes of a class, because theses properties can also be used to transport messages or information between a class and the surrounding application.

CIS = public(NOM) + public(VARS)

PHP_Depend uses the second variant and counts all public methods and attributes declared in a class to calculate its Class Interface Size metric.

This metric is a good indicator for the choosen software design. Several classes with a high CIS value are a sure sign that the design of the analyzed software prefers composition over inheritance to share common functionality between different components. So in most cases a high value is a good a sign, because composition increases the reusability and flexibility. But there are also situations where wrongly used composition of functionality leads to a design that is harder to understand and maintain.

Thresholds

It is not easy to define good thresholds for this metric, because those values heavy depend on the choosen design, e.g. inheritance or composition. But in generall we can say that is best practice to limit the public interface that can be used to alter the internal state of an object. Therefore we suggest 20 as a reference point for the upper limit.

Bibliography

[1]

http://www.ptidej.net/teaching/inf6306/fall09/notes/course4/Bansiya02-QualityModel.pdf

IEEE Transactions on Software Enginerring; Hierarchical Model for Object-Oriented Design Quality Assessment; Bansiya & Davis; 2002

Today I have released the second beta version of phpUnderControl. Beside several minor tweaks and bug fixes, this release contains one additional feature I was asked for during the IPC in Berlin. This feature allows you to specify a maximum number of log entries that will be shown in the generated metric charts. This can be very useful once you have a project with a great amount of builds and the chart rendering gets slower and slower.

This feature adds a new option --max-number to phpUnderControl's chart command. To rebuild all your charts you can call phpUnderControl's shell script with the following command:

  mapi@arwen ~ $ phpuc --force-update --max-number 42 \
                 /opt/cruisecontrol/logs/phpUnderControl \
                 /opt/cruisecontrol/logs/phpUnderControl

You can get the latest release of phpUnderControl through its pear channel:

  mapi@arwen ~ $ pear upgrade --alldeps phpuc/phpUnderControl-0.6.0beta2
  Starting to download phpUnderControl-0.6.0beta2.tgz (546,314 bytes)
  ...................................................................
  .............................done: 546,314 bytes

or you can get the latest development version on github.

Now that the founding of the Qafoo - Passion for software quality company is announced, it is time to present the consulting services which we will provide around the quality lifecycle of PHP applications.

The first series of services that we will provide is all around the high quality component library Zeta Components, formally known as eZ Components. The Zeta Components provide a loosely coupled set of unique and well thought out features, like the WebDAV server implementation, the Graph component which makes the generation of appealing charts very easy, or the widely used Mail component. Other aspects of the Zeta Components, which highlight our quality claim for the Qafoo GmbH, are the excessive documentation and the very high test coverage, which guarantees a consistently good product quality. Another key benefit of the Zeta Components are their loosely coupled structure, so that you can cherry pick some of the components and integrate them in your current application or framework infrastructure.

Based on the profound knowledge of Toby and Kore, two core developers behind the components for last five years, we will offer professional trainings and support that is backed by a company. Furthermore we provide paid-development and customization of the components to your own special needs.

Another point that speaks for the use of Zeta components is that the components are currently on their way to become an official project under the umbrella of the Apache Software Foundation, which guarantees a free use of the components, ensured by a stable legal basis.

So if you would like to use the Zeta Components for your projects or you are interested in a custom training, send us a mail to contact@qafoo.com.

As many of you may already have noticed, there will be a big change in my career as a professional software engineer and architect this summer. Together with Kore and Toby I am in the process of founding a company. The focus of this company will be on services all around the whole quality life cycle in PHP projects.

Under the hood of our company we will also offer support, trainings and consulting for several quality assurance tools, like pdepend, phpmd and phpUnderControl. For you, this opens a great opportunity. You can use the tools and the documentation, as well as participate in the community, as usual. But from now on you can also purchase professional support, if you get stuck or need general assitance. And when you miss a feature or need an individual extension for one of these tools, don't hesitate to contact us.

I am really excited what cool things will happen in the next couple of years and I am looking forward to cowork with professionals like Toby and Kore.

To finalize the little marketing for the company and its services I would appreciate to meet you, your colleagues and your compmany, to give presentations or into-depth trainings on one of the tools or on quality assurance in general.

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.

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 phpUnderControl version 0.5.1. It's a bug fix release that closes several issues open since a long time. First of all I would like to thank Sebastian Marek who was the main contributor to this releases, so a big thankyou to you.

• Now phpUnderControl should work with CruiseControl 2.8.3. Thanks to Mike van Riel who provided some hints on this issue in a blog comment.
• Fixed #983: Graph unitests throw fatal error when ezComponents not available.
• Fixed #966: phpcs-details.xsl not showing file name.
• Closed #863: Destination option is now deprecated.
• Fixed #862: Command line switches without parameter don't work.
• Fixed #861: Password is used as username in check outs. This patch was supplied by Thorsten Daners via e-mail.
• Fixed #734: Now the build dropdown redirects to the correct build uri.
• Implemented #703: PHPUnit test results are now the first entry on the project overview page.
• Fixed #700: Throw an exception when the specified project does not exist.
• Implemented #675: Use "php -l" for lint checking and not PHPUnit.
• Implemented #625: Integrate PHP_Depend results.

Beside the new release some more things have changed. From now on the phpUnderControl development is hosted on github. This means that from now on the latest version of phpUnderControl can be obtained with the following command:

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

Additionally we have moved the phpUnderControl's PEAR Channel Server from pear.phpunit.de to its own server pear.phpundercontrol.org. At this point I would like to thank Sebastian for providing phpUnderControl's infrastructure under the PHPUnit umbrella for the last three years.

mapi@arwen ~ $ pear uninstall phpunit/phpUnderControl
mapi@arwen ~ $ pear channel-discover pear.phpundercontrol.org
mapi@arwen ~ $ pear install --alldeps phpuc/phpUnderControl-beta
Starting to download phpUnderControl-0.5.1.tgz (539,717 bytes)
..........................................done: 539,717 bytes
install ok: channel://pear.phpundercontrol.org/phpUnderControl-0.5.1

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

After quite some time of silence around phpUnderControl I have bundled the 0.5.0 release today. Beside minor changes, bugfixes and enhancements this release contains one new major feature, the PHP_CodeBrowser.

phpUnderControl integrating PHP_CodeBrowser

The PHP_CodeBrowser is a separate application that collects various XML log files with different project metrics/violations and presents them in a browseable source view with syntax highligting. This tool is a contribution by the Mayflower GmbH, where it was developed and now shared with the Open Source Community. At this point I would like to thank Mayflower as a whole and in particular at Elger and Thorsten, which were responsible for all technical aspects of this contribution.

To use the PHP_CodeBrowser you must add an additional execute publisher to your CruiseControl config.xml file that generates the PHP_CodeBrowser html report and an additional artifacts publisher to move the generated PHP_CodeBrowser report into the projects artifacts directory.

<?xml version="1.0" encoding="UTF-8" ?>
<cruisecontrol>
  <!-- ... -->
  <project name="PHP_Depend" buildafterfailed="false">
    <!-- ... -->
    <publishers>
      <!-- ... -->
      <execute command="phpcb 
        --log projects/${project.name}/build/logs 
        --source projects/${project.name}/source/PHP 
        --output projects/${project.name}/build/php-code-browser"/>
      <artifactspublisher 
        dir="projects/${project.name}/build/php-code-browser" 
        dest="artifacts/${project.name}" 
        subdirectory="php-code-browser"/>
      <!-- ... -->
    </publishers>
  </project>
</cruisecontrol>

But why do we use a CruiseControl publishers instead of a regular ant (Your build tool here) target? The answer is really simple. The PHP_CodeBrowser must be the very last artifact generated for a project, which means it must also run after PHPUnit, to collect the test result logs. But in most setups PHPUnit is configured with failonerror="on" to mark a build as failed, when an error occured during the test execution. But with this configuration a following PHP_CodeBrowser target would never be executed by ant, because the build failed already. This cannot happen with a CruiseControl publisher which is always executed in a separated process.

If you create a new project with phpUnderControl's project command, phpUnderControl will automatically search for an installed PHP_CodeBrowser and add the required publishers to your config.xml file when it is present.

mapi@arwen ~ $ phpuc project \
       --project-name PHP_Depend \
       --source-dir PHP \
       --test-case PHP_Depend_AllTests \
       --test-dir tests \
       --test-file PHP/Depend/AllTests.php \
       --version-control svn \
       --version-control-url http://svn.pdepend.org/branches/0.9.0 \
       /opt/cruisecontrol/cruisecontrol-bin-2.8.2

To get the latest version of phpUnderControl, you can use the PEAR-Channel-Server:

mapi@arwen ~ $ pear channel-discover pear.phpunit.de
mapi@arwen ~ $ pear install phpunit/phpUnderControl-beta

or you can check it out from the subversion repository:

mapi@arwen ~ $ svn co svn://phpunit.de/phpunit/phpUnderControl/trunk

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.

Today Fabien Potencier announced the first relase of the PEAR Channel server Pirum. The great benefit of this Channel server is that it provides a simple shell script to publish new PEAR package releases, a feature that I missed in the previously used Chiara PEAR Server. Pirum will make it really easy to publish new package versions through a simple build script

The setup was quick done, following the instructions on the pirum website, and importing the existing package files worked like a charm. The only problem I encountered was that both channel server implementations use a different directory structure. Pirum stores all the XML descriptors under a directory named /rest, while my Chiara Server installation has used /Chiara_PEAR_Server_REST, so that a first call to pear upgrade resulted in the following error:

manu@arwen ~ $ pear upgrade
Error getting channel info from pear.pdepend.org: \
File http://pear.pdepend.org:80/Chiara_PEAR_Server_REST/p/packages.xml \
not valid (received: HTTP/1.1 404 Not Found)

But a simple 301 redirect makes this software transition transparent for the PHP_Depend users. So when you will also switch to Pirum you should keep this in mind and test your channel server with an existing/configured local pear installation.

Finally, thanks to Fabien for this nitty-gritty tool, which will speed up the deployment process of PEAR packages, at least for me.

Today I had the chance to visit Derick's IPC talk PHP on the D-BUS. Beside the fact that it was an exciting talk, it inspired me to implement a small, but nice feature for PHP_Depend using the pecl/dbus extension.

PHP_Depend jumps on the D-BUS

Sometimes the parsing and analysis process of PHP_Depend can consume a lot of time to finish, so I always put the shell aside and do something different. Normally I take a look at the shell every few minutes to check if the process has finished, but it also happens that I totally forget that I have started a PHP_Depend process on my system. So I need something that says to me, "Hey, mapi PHP_Depend has finished its job...", and here comes D-BUS in the game.

With D-BUS it is really simple to send a message to a desktop notification panel, as it is available for desktop environments like Gnome or KDE. To use D-BUS in your php applications you must checkout the source code of pecl/dbus from the svn repository and compile it for your php installation.

mapi@arwen ~ $ svn co http://svn.php.net/repository/pecl/dbus/trunk \
               pecl-dbus
mapi@arwen ~ $ cd pecl-dbus
mapi@arwen pecl-dbus $ phpize
mapi@arwen pecl-dbus $ ./configure
mapi@arwen pecl-dbus $ make
mapi@arwen pecl-dbus $ sudo make install

That's it. Now you should see the --notify-me option when you open PHP_Depend's help screen.

mapi@arwen ~ $ ~/pdepend/pdepend.php --help
PHP_Depend @package_version@ by Manuel Pichler

// ... snipp ...

  --debug                   Prints debugging information.
  --help                    Print this help text.
  --version                 Print the current version.
  --notify-me               Show a notification after analysis.
  -d key[=value]            Sets a php.ini value.

Now you can add this option to your normal PHP_Depend command and it will show a notification window with the number of analyzed files and the time the process took.

mapi@arwen ~ $ ~/pdepend/pdepend.php --summary-xml=/tmp/summary.xml \
                                       --notify-me \
                                       ~/pdepend/PHP

For the moment this feature is only available through the 0.9.0 branch of PHP_Depend and not as a PEAR package.

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