PHP Depend (pdepend) ignores @package and uses namespaces as packages instead

Question

I tried to compare the metrics of some PHP frameworks with PHP Depend and ran into annoying and probably unintended behavior:

The @package annotation is being ignored, instead namespaces are treated as packages. This is a problem since often sub namespaces are used that are not meant as separate packages (i.e. SomePackage\Exception)

Example class file

<?php
/**
 * 
 * This file is part of the Aura Project for PHP.
 * 
 * @package Aura.Di
 * 
 * @license http://opensource.org/licenses/bsd-license.php BSD
 * 
 */
namespace Aura\Di\Exception;

use Aura\Di\Exception;

/**
 * 
 * The named DI container already exists.
 * 
 * @package Aura.Di
 * 
 */
class ContainerExists extends Exception
{
}

Example report

  <package name="Aura\Di\Exception" cr="0.15" noc="5" nof="0" noi="0" nom="0" rcr="0.28114285714286">
    ...
  </package>

Now my question is: What's the reason for this and how can I fix it?

Answer 1

@package was a pseudo-namespacing technique back before PHP gained true namespaces in 5.3. As such, I think pretty much every static code processing tool around is written to choose namespaces when they exist, and only fall back to using @package if no namespacing exists. The idea of continuing to use @package as a different grouping mechanism on top of namespaces has been mentioned on occasion, particularly with regard to phpDocumentor, but I'm not aware of any efforts to truly implement such behavior in any of these kinds of apps.