From d8699396f5a2db3fabcf29d62e4df53789eac887 Mon Sep 17 00:00:00 2001
From: Abdul Malik Ikhsan <samsonasik@gmail.com>
Date: Wed, 15 Jul 2026 21:04:02 +0700
Subject: [PATCH] Add `PYRAMETER_DISABLED` environment variable opt-out

---
 README.md                    | 12 ++++++++++++
 src/Extension.php            |  6 ++++++
 tests/ExtensionSmokeTest.php | 33 +++++++++++++++++++++++++++++++--
 tests/ExtensionTest.php      | 24 ++++++++++++++++++++++++
 4 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 118d76e..0be6fb3 100644
--- a/README.md
+++ b/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
diff --git a/src/Extension.php b/src/Extension.php
index 1f2ebb5..8ccca35 100644
--- a/src/Extension.php
+++ b/src/Extension.php
@@ -17,6 +17,8 @@
 use PHPUnit\Runner\Extension\ParameterCollection;
 use PHPUnit\TextUI\Configuration\Configuration;
 
+use function getenv;
+
 final class Extension implements PHPUnitExtension
 {
     public function bootstrap(
@@ -24,6 +26,10 @@ public function bootstrap(
         Facade $facade,
         ParameterCollection $parameters,
     ): void {
+        if (getenv('PYRAMETER_DISABLED') === '1') {
+            return;
+        }
+
         $pyrameterConfig  = PyrameterConfigLoader::loadFromParametersOrDefaults($parameters);
         $testCollector    = new TestCollector();
         $testUsageScanner = new TestUsageScanner();
diff --git a/tests/ExtensionSmokeTest.php b/tests/ExtensionSmokeTest.php
index 1d664d1..4633c57 100644
--- a/tests/ExtensionSmokeTest.php
+++ b/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)];
     }
diff --git a/tests/ExtensionTest.php b/tests/ExtensionTest.php
index 44eaa0d..7f0c7dc 100644
--- a/tests/ExtensionTest.php
+++ b/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';