Add PYRAMETER_DISABLED environment variable opt-out

README.md

@@ -78,6 +78,18 @@ vendor/bin/phpunit
 
 This uses the default rules and target shape.
 
+### Disable Pyrameter for one run
+
+Set `PYRAMETER_DISABLED` to `1` to run PHPUnit without Pyrameter collecting tests,
+printing a report, or enforcing target violations:
+
+```bash
+PYRAMETER_DISABLED=1 vendor/bin/phpunit
+```
+
+The extension remains configured in `phpunit.xml`, but it does not register any
+subscribers for that run. Other values do not disable Pyrameter.
+
 ## Configure
 
 ### Default or empty configuration

src/Extension.php

@@ -17,13 +17,19 @@
 use PHPUnit\Runner\Extension\ParameterCollection;
 use PHPUnit\TextUI\Configuration\Configuration;
 
+use function getenv;
+
 final class Extension implements PHPUnitExtension
 {
     public function bootstrap(
         Configuration $configuration,
         Facade $facade,
         ParameterCollection $parameters,
     ): void {
+        if (getenv('PYRAMETER_DISABLED') === '1') {
+            return;
+        }
+
         $pyrameterConfig  = PyrameterConfigLoader::loadFromParametersOrDefaults($parameters);
         $testCollector    = new TestCollector();
         $testUsageScanner = new TestUsageScanner();

tests/ExtensionSmokeTest.php

@@ -8,7 +8,9 @@
 
 use function escapeshellarg;
 use function exec;
+use function getenv;
 use function implode;
+use function putenv;
 use function sprintf;
 
 use const PHP_BINARY;
@@ -28,6 +30,17 @@ public function testItRegistersWithPhpunitAndPrintsAReportAfterExecution(): void
         $this->assertStringContainsString('Total: 2 tests', $output);
     }
 
+    public function testItCanBeDisabledByEnvironmentVariable(): void
+    {
+        $configuration       = __DIR__ . '/Fixtures/SmokeProject/phpunit.xml';
+        [$exitCode, $output] = $this->runPhpUnit($configuration, disabled: true);
+
+        $this->assertSame(0, $exitCode, $output);
+        $this->assertStringContainsString('OK (2 tests, 2 assertions)', $output);
+        $this->assertStringNotContainsString('Pyrameter', $output);
+        $this->assertStringNotContainsString('Shape:', $output);
+    }
+
     public function testFailOnViolationChangesPhpunitExitCodeWithoutSubscriberWarning(): void
     {
         $configuration       = __DIR__ . '/Fixtures/SmokeProject/phpunit-fail.xml';
@@ -58,7 +71,7 @@ public function testFailOnViolationDoesNotHidePhpunitFailureDetails(): void
     /**
      * @return array{int, string}
      */
-    private function runPhpUnit(string $configuration): array
+    private function runPhpUnit(string $configuration, bool $disabled = false): array
     {
         $phpunit = __DIR__ . '/../vendor/bin/phpunit';
         $command = sprintf(
@@ -68,7 +81,23 @@ private function runPhpUnit(string $configuration): array
             escapeshellarg($configuration),
         );
 
-        exec($command, $lines, $exitCode);
+        $originalValue = getenv('PYRAMETER_DISABLED');
+
+        if ($disabled) {
+            putenv('PYRAMETER_DISABLED=1');
+        }
+
+        try {
+            exec($command, $lines, $exitCode);
+        } finally {
+            if ($disabled) {
+                if ($originalValue === false) {
+                    putenv('PYRAMETER_DISABLED');
+                } else {
+                    putenv('PYRAMETER_DISABLED=' . $originalValue);
+                }
+            }
+        }
 
         return [$exitCode, implode(PHP_EOL, $lines)];
     }

tests/ExtensionTest.php

@@ -16,12 +16,36 @@
 
 use function class_exists;
 use function file_put_contents;
+use function getenv;
+use function putenv;
 use function str_replace;
 use function sys_get_temp_dir;
 use function unlink;
 
 final class ExtensionTest extends TestCase
 {
+    public function testItDoesNotBootstrapWhenDisabledByEnvironmentVariable(): void
+    {
+        $originalValue = getenv('PYRAMETER_DISABLED');
+        putenv('PYRAMETER_DISABLED=1');
+
+        try {
+            (new Extension())->bootstrap(
+                (new ReflectionClass(Configuration::class))->newInstanceWithoutConstructor(),
+                $this->extensionFacade(),
+                ParameterCollection::fromArray(['config' => '/missing/pyrameter.php']),
+            );
+        } finally {
+            if ($originalValue === false) {
+                putenv('PYRAMETER_DISABLED');
+            } else {
+                putenv('PYRAMETER_DISABLED=' . $originalValue);
+            }
+        }
+
+        self::addToAssertionCount(1);
+    }
+
     public function testItBootstrapsThePhpunitSubscribers(): void
     {
         $configFile = sys_get_temp_dir() . '/pyrameter-extension-test.php';