Wrap the concept of being enabled

Author: matthiasnoback

README.md

@@ -19,17 +19,20 @@ In your front controller (e.g. `index.php`), add the following:
 
 use LiveCodeCoverage\LiveCodeCoverage;
 
-$liveCodeCoverage = LiveCodeCoverage::bootstrap(
+$shutDownCodeCoverage = LiveCodeCoverage::bootstrap(
+    function () { return (bool)getenv('CODE_COVERAGE_ENABLED'); },
     __DIR__ . '/../var/coverage',
     __DIR__ . '/../phpunit.xml.dist'
 );
 
-// Run your web application now
+// Run your web application now...
 
-$liveCodeCoverage->stopAndSave();
+// This will save and store collected coverage data:
+$shutDownCodeCoverage();
 ```
 
-- The first argument is the directory where all the collected coverage data will be stored (`*.cov` files). This directory should already exist and be writable.
+- The first argument passed to `LiveCodeCoverage::bootstrap()` is a callable that will be used to determine if code coverage is enabled at all. The example shows how you can use an environment variable for that. Make 
+- The second argument is the directory where all the collected coverage data will be stored (`*.cov` files). If this directory doesn't exist yet, it will be created.
 - The second argument is the path to a PHPUnit configuration file. Its `<filter>` section will be used to configure the code coverage whitelist. For example, this `phpunit.xml.dist` file might look something like this:
 
 ```xml
@@ -50,12 +53,12 @@ If you don't provide a PHPUnit configuration file, no filters will be applied, s
 If your application is a legacy application which `exit()`s or `die()`s before execution reaches the end of your front controller, the bootstrap should be slightly different:
 
 ```php
-$liveCodeCoverage = LiveCodeCoverage::bootstrap(
+$shutDownCodeCoverage = LiveCodeCoverage::bootstrap(
     // ...
 );
-$liveCodeCoverage->stopAndSaveOnExit();
+register_shutdown_function($shutDownCodeCoverage);
 
-// Run your web application now
+// Run your web application now...
 ```
 
 ## Generating code coverage reports (HTML, Clover, etc.)

src/LiveCodeCoverage/LiveCodeCoverage.php

@@ -29,8 +29,22 @@ private function __construct(CodeCoverage $codeCoverage, $storageDirectory, $cov
         $this->storageDirectory = $storageDirectory;
     }
 
-    public static function bootstrap($storageDirectory, $phpunitConfigFilePath = null, $coverageId = 'live-coverage')
+    /**
+     * @param callable $coverageEnabled
+     * @param string $storageDirectory
+     * @param string|null $phpunitConfigFilePath
+     * @param string $coverageId
+     * @return callable
+     */
+    public static function bootstrap($coverageEnabled, $storageDirectory, $phpunitConfigFilePath = null, $coverageId = 'live-coverage')
     {
+        Assert::isCallable($coverageEnabled);
+        if (!$coverageEnabled()) {
+            return function () {
+                // do nothing - code coverage is not enabled
+            };
+        }
+
         if ($phpunitConfigFilePath !== null) {
             Assert::file($phpunitConfigFilePath);
             $codeCoverage = CodeCoverageFactory::createFromPhpUnitConfiguration($phpunitConfigFilePath);
@@ -42,25 +56,38 @@ public static function bootstrap($storageDirectory, $phpunitConfigFilePath = nul
 
         $liveCodeCoverage->start();
 
-        return $liveCodeCoverage;
+        return [$liveCodeCoverage, 'stopAndSave'];
     }
 
-    public static function bootstrapRemoteCoverage($storageDirectory, $phpunitConfigFilePath = null)
+    /**
+     * @param callable $coverageEnabled
+     * @param string $storageDirectory
+     * @param null $phpunitConfigFilePath
+     * @return callable
+     */
+    public static function bootstrapRemoteCoverage($coverageEnabled, $storageDirectory, $phpunitConfigFilePath = null)
     {
+        Assert::isCallable($coverageEnabled);
+        if (!$coverageEnabled()) {
+            return function () {
+                // do nothing - code coverage is not enabled
+            };
+        }
+
         $coverageGroup = isset($_GET['coverage_group']) ? $_GET['coverage_group'] :
             (isset($_COOKIE['coverage_group']) ? $_COOKIE['coverage_group'] : null);
 
-        $coverageId = isset($_GET['coverage_id']) ? $_GET['coverage_id'] :
-            (isset($_COOKIE['coverage_id']) ? $_COOKIE['coverage_id'] : 'live-coverage');
-
         $storageDirectory .= ($coverageGroup ? '/' . $coverageGroup : '');
 
         if (isset($_GET['export_code_coverage'])) {
             self::exportCoverageData($storageDirectory);
             exit;
         }
 
-        return self::bootstrap($storageDirectory, $phpunitConfigFilePath, $coverageId);
+        $coverageId = isset($_GET['coverage_id']) ? $_GET['coverage_id'] :
+            (isset($_COOKIE['coverage_id']) ? $_COOKIE['coverage_id'] : 'live-coverage');
+
+        return self::bootstrap($coverageEnabled, $storageDirectory, $phpunitConfigFilePath, $coverageId);
     }
 
     private function start()
@@ -80,11 +107,6 @@ public static function exportCoverageData($coverageDirectory)
         echo serialize($codeCoverage);
     }
 
-    public function stopAndSaveOnExit()
-    {
-        register_shutdown_function([$this, 'stopAndSave']);
-    }
-
     public function stopAndSave()
     {
         $this->codeCoverage->stop();

test/functional/prepend.php

@@ -2,5 +2,9 @@
 
 use LiveCodeCoverage\LiveCodeCoverage;
 
-$liveCodeCoverage = LiveCodeCoverage::bootstrap(__DIR__ . '/coverage', __DIR__ . '/phpunit.xml.dist');
-$liveCodeCoverage->stopAndSaveOnExit();
+$shutDownCodeCoverage = LiveCodeCoverage::bootstrap(
+    function() { return true; },
+    __DIR__ . '/coverage',
+    __DIR__ . '/phpunit.xml.dist'
+);
+register_shutdown_function($shutDownCodeCoverage);