Merge pull request #6 from Halleck45/HenryAndKafura

Coupling

Author: Jean-François Lépine

README.md

@@ -17,10 +17,32 @@ Will output:
 
 ## Bubbles chart and complete report
 
-If you want to get the HTMl report (with charts):
+If you want to get the summary HTML report (with charts):
 
     php ./bin/metrics.php --summary-html=/path/of/your/choice.html <folder or filename>
 
+You can change the depth of the summary report with the `--level=<value>` option.
+
+If you want to have a detailled view (file by file):
+
+    php ./bin/metrics.php --details-html=/path/of/your/choice.html <folder or filename>
+
+## Informations about OOP model
+
+If you want to get informations about OOP model (coupling, instability...), you should pass the `--oop` parameter:
+
+    php ./bin/metrics.php --oop <folder or filename>
+
+Remember that this feature parse all files, extract declared classes, dependencies of each method... and is really *very slow*.
+
+## Jenkins and PIC integration
+
+You can easily export resut to XML with the `--summary-xml` option:
+
+    php ./bin/metrics.php --summary-xml=/path/of/your/choice.xml <folder or filename>
+
+You will find a tutorial to [integrate PhpMetrics report to Jenkins here](blog.lepine.pro/industrialisation/indice-de-maintenabilite-dun-projet-php-et-jenkins) (in French).
+
 ### Read report
 
 + Each file is symbolized by a circle
@@ -86,6 +108,17 @@ Comment weight represents the impact of documentation in code.
     perCM = commentLoc / loc
     MIcw = 50 * sin(sqrt(2.4 * perCM))
 
+## Coupling and instability
+
+Coupling use two metrics:
+
++ Afferent coupling (CA): number of classes that your classes affects
++ Efferent coupling (CE) : number of classes used by your class
+
+Instability concerns the risk of your class, according coupling:
+
+    I = CE / (CA + CE)
+
 # Use it in code
 
 ## Halstead
@@ -113,6 +146,47 @@ $maintenability = new \MaintenabilityIndex\MaintenabilityIndex;
 $rMaintenability = $maintenability->calculate($rHalstead, $rLoc);
 var_dump($rMaintenability);
 ```
+
+## OOP Extractor
+
+Extracts OOP model of files, and map classes and files:
+
+```php
+$extractor = new Extractor();
+$rOOP = $extractor->extract($filename);
+var_dump($rOOP);
+```
+
+## Coupling
+
+Calculate coupling.
+
+```php
+// build class map
+$classMap = new ClassMap;
+foreach($files as $filename) {
+    $extractor = new Extractor();
+    $rOOP = $extractor->extract($filename);
+    $classMap->push($filename, $rOOP);
+}
+// coupling
+$coupling = new Coupling;
+$couplingMap = $coupling->calculate($classMap);
+$rCoupling = $couplingMap->get('\My\Namespace\ClassName');
+var_dump($rCoupling);
+```
+
+If you want to work with files instead of classes:
+
+```php
+// reuse code above, then
+$fileCoupling = new FileCoupling($classMap, $couplingMap);
+$rCoupling = $fileCoupling->calculate('/path/to/file.php');
+var_dump($rCoupling);
+```
+
+
+
 # Contribute
 
 In order to run unit tests, please install dev dependencies:

bin/metrics.php

@@ -18,5 +18,5 @@ function includeIfExists($file)
     );
 }
 
-$app = new Hal\Console\PhpMetricsApplication('PhpMetrics, by Jean-François Lépine (https://twitter.com/Halleck45)', '0.0.3');
+$app = new Hal\Console\PhpMetricsApplication('PhpMetrics, by Jean-François Lépine (https://twitter.com/Halleck45)', '0.0.4');
 $app->run();

build.php

@@ -19,8 +19,6 @@
     $phar->addFromString($path, file_get_contents($file));
 }
 
-$phar->addFromString('init.php', file_get_contents(__DIR__.'/init.php'));
-
 $phar->setStub(<<<STUB
 <?php
 
@@ -36,7 +34,7 @@
 Phar::mapPhar('metrics.phar');
 
 require_once 'phar://metrics.phar/vendor/autoload.php';
-\$app = new Hal\Console\PhpMetricsApplication('PhpMetrics, by Jean-François Lépine (https://twitter.com/Halleck45)', '0.0.3');
+\$app = new Hal\Console\PhpMetricsApplication('PhpMetrics, by Jean-François Lépine (https://twitter.com/Halleck45)', '0.0.4');
 \$app->run();
 
 __HALT_COMPILER();

build/metrics.phar

@@ -97,6 +97,13 @@ public function getSum($key) {
         return isset($this->sum[$key]) ? $this->sum[$key] : null;
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function has($key) {
+        return isset($this->sum[$key]);
+    }
+
     /**
      * @inheritdoc
      */

src/Hal/Bounds/Result/BoundsResult.php

@@ -88,6 +88,13 @@ public function asArray() {
         ));
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function has($key) {
+        return $this->bounds->has($key);
+    }
+
     /**
      * @inheritdoc
      */

src/Hal/Bounds/Result/DirectoryResult.php

@@ -57,4 +57,12 @@ public function getSum($key);
      * @return null|float
      */
     public function get($type, $key);
+
+    /**
+     * Has key ?
+     *
+     * @param $key
+     * @return mixed
+     */
+    public function has($key);
 }

src/Hal/Bounds/Result/ResultInterface.php

@@ -8,7 +8,12 @@
  */
 
 namespace Hal\Command\Job;
+use Hal\Coupling\Coupling;
+use Hal\Coupling\FileCoupling;
 use Hal\File\Finder;
+use Hal\OOP\Extractor\ClassMap;
+use Hal\OOP\Extractor\Extractor;
+use Hal\OOP\Extractor\Result;
 use Hal\Result\ResultCollection;
 use Symfony\Component\Console\Helper\ProgressHelper;
 use Symfony\Component\Console\Output\OutputInterface;
@@ -43,18 +48,27 @@ class DoAnalyze implements JobInterface
      */
     private $finder;
 
+    /**
+     * do OOP analyze ?
+     *
+     * @var bool
+     */
+    private $withOOP;
+
     /**
      * Constructor
      *
      * @param OutputInterface $output
      * @param Finder $finder
      * @param string $path
+     * @param bool $withOOP
      */
-    function __construct(OutputInterface $output, Finder $finder, $path)
+    function __construct(OutputInterface $output, Finder $finder, $path, $withOOP)
     {
         $this->output = $output;
         $this->finder = $finder;
         $this->path = $path;
+        $this->withOOP = $withOOP;
     }
 
     /**
@@ -71,32 +85,62 @@ public function execute(ResultCollection $collection) {
         $progress = new ProgressHelper();
         $progress->start($this->output, sizeof($files, COUNT_NORMAL));
 
+        // class map
+        $classMap = new ClassMap();
+
+        $halstead = new \Hal\Halstead\Halstead(new \Hal\Token\TokenType());
+        $maintenability = new \Hal\MaintenabilityIndex\MaintenabilityIndex;
+        $loc = new \Hal\Loc\Loc();
+        $extractor = new Extractor();
+
         foreach($files as $filename) {
 
             $progress->advance();
 
-            // calculates
-            $halstead = new \Hal\Halstead\Halstead(new \Hal\Token\TokenType());
+            // HALSTEAD
             $rHalstead = $halstead->calculate($filename);
 
-            $loc = new \Hal\Loc\Loc();
+            // LOC
             $rLoc = $loc->calculate($filename);
 
-            $maintenability = new \Hal\MaintenabilityIndex\MaintenabilityIndex;
+            // Maintenability Index
             $rMaintenability = $maintenability->calculate($rHalstead, $rLoc);
 
+
             // formats
-            $resultSet = new \Hal\Result\ResultSet(basename($this->path) . str_replace($this->path, '', $filename));
+            $resultSet = new \Hal\Result\ResultSet($filename);
             $resultSet
                 ->setLoc($rLoc)
                 ->setHalstead($rHalstead)
                 ->setMaintenabilityIndex($rMaintenability);
 
+            if($this->withOOP) {
+                // OOP
+                $rOOP = $extractor->extract($filename);
+                $classMap->push($filename, $rOOP);
+                $resultSet->setOOP($rOOP);
+            }
+
+
             $collection->push($resultSet);
         }
-
         $progress->clear();
         $progress->finish();
+
+        if($this->withOOP) {
+            // COUPLING (should be done after parsing files)
+            $this->output->writeln('Analyzing coupling. This will take few minutes...');
+
+            $coupling = new Coupling();
+            $couplingMap = $coupling->calculate($classMap);
+
+            // link between coupling and files
+            $fileCoupling = new FileCoupling($classMap, $couplingMap);
+            foreach($files as $filename) {
+                $rCoupling = $fileCoupling->calculate($filename);
+                $collection->get($filename)->setCoupling($rCoupling);
+            }
+        }
     }
 
 }

src/Hal/Command/Job/DoAnalyze.php

@@ -57,6 +57,9 @@ protected function configure()
                 ->addOption(
                         'extensions', null, InputOption::VALUE_REQUIRED, 'Regex of extensions to include', 'php'
                 )
+                ->addOption(
+                        'oop', null, InputOption::VALUE_NONE, 'If provided, tool will extract informations about OOP model'
+                )
         ;
     }
 
@@ -85,7 +88,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
         // jobs queue planning
         $queue = new Queue();
         $queue
-            ->push(new DoAnalyze($output, $finder, $input->getArgument('path')))
+            ->push(new DoAnalyze($output, $finder, $input->getArgument('path'), $input->getOption('oop')))
             ->push(new SearchBounds($output, $bounds))
             ->push(new SearchBounds($output, $directoryBounds))
             ->push(new ReportRenderer($output, new Summary\Cli($validator, $bounds, $directoryBounds)))

src/Hal/Command/RunMetricsCommand.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * (c) Jean-François Lépine <https://twitter.com/Halleck45>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Hal\Coupling;
+use Hal\OOP\Extractor\ClassMap;
+
+
+/**
+ * Estimates coupling (based on work of Henry And Kafura)
+ *
+ * @author Jean-François Lépine <https://twitter.com/Halleck45>
+ */
+class Coupling {
+
+    /**
+     * Calculates coupling
+     *
+     * @param ClassMap $result
+     * @return ResultMap
+     */
+    public function calculate(ClassMap $result)
+    {
+        $map = $this->extractCoupling($result);
+
+        // instability
+        foreach($map as &$class) {
+            if($class->getAfferentCoupling() + $class->getEfferentCoupling() > 0) {
+                $class->setInstability($class->getEfferentCoupling() / ($class->getAfferentCoupling() + $class->getEfferentCoupling()));
+            }
+        }
+
+        return new ResultMap($map);
+    }
+
+
+    /**
+     * Extracts afferent and efferent coupling
+     *
+     * @param ClassMap $result
+     * @return array
+     */
+    private function extractCoupling(ClassMap $result) {
+        $results = $result->all();
+
+        $classes = array();
+        foreach($results as $result) {
+            $classes = array_merge($classes, $result->getClasses());
+        }
+
+        $map = array();
+        foreach($classes as $class) {
+
+            if(!isset($map[$class->getName()])) {
+                $map[$class->getName()] = new Result($class->getName());
+            }
+
+            $dependencies = $class->getDependencies();
+            $map[$class->getName()]->setEfferentCoupling(sizeof($dependencies, COUNT_NORMAL));
+
+            foreach($dependencies as $dependency) {
+
+                if(!isset($map[$dependency])) {
+                    $map[$dependency] = new Result($dependency);
+                }
+                $map[$dependency]->setAfferentCoupling($map[$dependency]->getAfferentCoupling() + 1);
+            }
+        }
+        return $map;
+    }
+};