Memoised the container probe and de-duplicated the contextualize dispatch. (#104)

Author: AlexSkrypnyk

benchmarks/README.md

@@ -25,13 +25,13 @@ Reference points from the CI runner (Linux, PHP 8.3) - the same environment the
 
 Peak memory is ~2 MB across all subjects.
 
-## Optimization opportunities
+## Optimization notes
 
-Candidates for a dedicated performance pass, with the evidence the suite surfaces:
+What the suite surfaced, and where it landed:
 
-1. **Native-host detection cost.** `benchDetectDrupalNative` (~41 μs) is dramatically slower than `benchDetectDrupalContainer` (~12 μs) despite the container doing more contextualization work. The native path pays for `Container::isContainer()`'s filesystem probes (`file_exists('/.dockerenv')`, `file_exists('/.dockerinit')`, `is_readable('/proc/1/cgroup')`) and, during contextualization, the reflection fallback in `AbstractStack::contextualize()` / `AbstractPlatform::contextualize()` (`Native` is not a `DrupalContextualizerInterface`, so a method name is built via `ReflectionClass::getShortName()`). The container path short-circuits `isContainer()` on an env var and dispatches through the typed fast path. This gap is the suite's clearest optimization target.
-2. **`is()` re-reads the env var.** `Environment::is()` calls `getenv('ENVIRONMENT_TYPE')` on every invocation even though the type is already resolved. Caching it in a static property realizes the documented "statically cached" design and speeds the repeated-check path.
-3. **Duplicated dispatch.** `AbstractPlatform::contextualize()` and `AbstractStack::contextualize()` are identical; the shared dispatch can move to a trait.
+1. **Container probing ran per stack.** Every container-family stack (Ddev, Lando, Container) inherits `Container::isContainer()`, so a single native-host detection re-ran the same env/filesystem probe up to three times. `Container::isContainer()` now memoises its result for the run (cleared on `Environment::reset()`), so the probe runs once while a subclass overriding `isContainer()` still opts out. This cut `benchDetectDrupalNative` by ~19% locally (more on Linux, where the probe actually reads `/proc/1/cgroup`). The remaining single probe is inherent to detecting containerisation.
+2. **Duplicated dispatch.** `AbstractPlatform::contextualize()` and `AbstractStack::contextualize()` were byte-identical; they now share the `DispatchesContextualization` trait, which dispatches the built-in Drupal context through its typed interface and falls back to reflection only for custom contexts.
+3. **`is()` reads the env var, by design.** `Environment::is()` calls `getenv('ENVIRONMENT_TYPE')` each time. This is deliberate: the env var is the single source of truth for the type - both the override input and the published output. Caching it in a static would create a second store that can silently diverge, so the per-call `getenv()` stays.
 
 ## Comparison and baseline
 

src/DispatchesContextualization.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\EnvironmentDetector;
+
+use DrevOps\EnvironmentDetector\Contexts\ContextInterface;
+use DrevOps\EnvironmentDetector\Contexts\Drupal;
+use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
+
+/**
+ * Dispatches a context to the matching per-context method on a ring.
+ *
+ * Shared by platforms and stacks so both apply context-specific settings the
+ * same way.
+ *
+ * @package DrevOps\EnvironmentDetector
+ */
+trait DispatchesContextualization {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function contextualize(ContextInterface $context): void {
+    // The built-in Drupal context is dispatched through the typed interface so
+    // the common path never pays for reflection; a ring that does not
+    // contextualize Drupal is simply a no-op here.
+    if ($context instanceof Drupal) {
+      if ($this instanceof DrupalContextualizerInterface) {
+        $this->contextualizeDrupal($context);
+      }
+
+      return;
+    }
+
+    // A custom context falls back to a contextualize<ContextName>() method
+    // resolved from its short name, when the ring defines one.
+    $method = 'contextualize' . (new \ReflectionClass($context))->getShortName();
+    $callable = [$this, $method];
+
+    if (is_callable($callable)) {
+      $callable($context);
+    }
+  }
+
+}

src/Environment.php

@@ -367,6 +367,11 @@ public static function reset(bool $all = FALSE): void {
     static::$contexts = NULL;
     static::$isInitialized = FALSE;
 
+    // The container probe caches its result for the run; clearing it lets the
+    // next detection re-probe, which a test simulating a different host relies
+    // on.
+    Container::resetCache();
+
     if ($all) {
       static::$fallback = self::DEVELOPMENT;
     }

src/Platforms/AbstractPlatform.php

@@ -4,9 +4,7 @@
 
 namespace DrevOps\EnvironmentDetector\Platforms;
 
-use DrevOps\EnvironmentDetector\Contexts\ContextInterface;
-use DrevOps\EnvironmentDetector\Contexts\Drupal;
-use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
+use DrevOps\EnvironmentDetector\DispatchesContextualization;
 
 /**
  * Abstract platform.
@@ -17,6 +15,8 @@
  */
 abstract class AbstractPlatform implements PlatformInterface {
 
+  use DispatchesContextualization;
+
   /**
    * Platform ID. Platforms should override this constant.
    */
@@ -34,26 +34,4 @@ public function id(): string {
     return static::ID;
   }
 
-  /**
-   * {@inheritdoc}
-   */
-  public function contextualize(ContextInterface $context): void {
-    // Known interfaces - optimised for speed.
-    if ($this instanceof DrupalContextualizerInterface && $context instanceof Drupal) {
-      // Only the most-derived contextualizeDrupal() runs, so a subclass that
-      // overrides it must call parent::contextualizeDrupal() to keep the
-      // parent's settings.
-      $this->contextualizeDrupal($context);
-      return;
-    }
-
-    // Runtime.
-    $method = 'contextualize' . (new \ReflectionClass($context))->getShortName();
-    $callable = [$this, $method];
-
-    if (is_callable($callable)) {
-      $callable($context);
-    }
-  }
-
 }

src/Stacks/AbstractStack.php

@@ -4,9 +4,7 @@
 
 namespace DrevOps\EnvironmentDetector\Stacks;
 
-use DrevOps\EnvironmentDetector\Contexts\ContextInterface;
-use DrevOps\EnvironmentDetector\Contexts\Drupal;
-use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
+use DrevOps\EnvironmentDetector\DispatchesContextualization;
 
 /**
  * Abstract stack.
@@ -17,6 +15,8 @@
  */
 abstract class AbstractStack implements StackInterface {
 
+  use DispatchesContextualization;
+
   /**
    * Stack ID. Stacks should override this constant.
    */
@@ -29,26 +29,4 @@ public function id(): string {
     return static::ID;
   }
 
-  /**
-   * {@inheritdoc}
-   */
-  public function contextualize(ContextInterface $context): void {
-    // Known interfaces - optimised for speed.
-    if ($this instanceof DrupalContextualizerInterface && $context instanceof Drupal) {
-      // Only the most-derived contextualizeDrupal() runs, so a subclass that
-      // overrides it must call parent::contextualizeDrupal() to keep the
-      // parent's settings.
-      $this->contextualizeDrupal($context);
-      return;
-    }
-
-    // Runtime.
-    $method = 'contextualize' . (new \ReflectionClass($context))->getShortName();
-    $callable = [$this, $method];
-
-    if (is_callable($callable)) {
-      $callable($context);
-    }
-  }
-
 }

src/Stacks/Container.php

@@ -26,6 +26,11 @@ class Container extends AbstractStack implements DrupalContextualizerInterface {
    */
   public const SERVICE_HOSTS = ['web', 'app', 'webserver', 'nginx', 'apache', 'apache2'];
 
+  /**
+   * Cached result of the container probe, shared across the run.
+   */
+  protected static ?bool $cachedIsContainer = NULL;
+
   /**
    * {@inheritdoc}
    */
@@ -40,6 +45,28 @@ public function active(): bool {
    *   TRUE if running inside a container, FALSE otherwise.
    */
   public function isContainer(): bool {
+    // Containerisation is fixed for the lifetime of the process, so the probe
+    // runs once and the result is shared across every container-family stack
+    // that inherits this method (Ddev, Lando and the generic container would
+    // otherwise each re-run it). A subclass overriding isContainer() opts out
+    // of the cache and is probed on its own terms.
+    return self::$cachedIsContainer ??= $this->detectContainer();
+  }
+
+  /**
+   * Reset the cached container probe so the next detection re-runs it.
+   */
+  public static function resetCache(): void {
+    self::$cachedIsContainer = NULL;
+  }
+
+  /**
+   * Probe the host for the signals that indicate a container.
+   *
+   * @return bool
+   *   TRUE if running inside a container, FALSE otherwise.
+   */
+  protected function detectContainer(): bool {
     // No single marker reliably proves containerisation across runtimes, so
     // probe several independent signals in turn: env vars set by tooling, the
     // engine-created marker files, then the control group of PID 1.

tests/Platforms/AbstractPlatformTest.php

@@ -6,12 +6,15 @@
 
 use DrevOps\EnvironmentDetector\Contexts\Drupal;
 use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
+use DrevOps\EnvironmentDetector\DispatchesContextualization;
 use DrevOps\EnvironmentDetector\Platforms\AbstractPlatform;
 use DrevOps\EnvironmentDetector\Tests\EnvironmentDetectorTestCase;
 use DrevOps\EnvironmentDetector\Tests\Fixtures\NotDrupalContext;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversTrait;
 
 #[CoversClass(AbstractPlatform::class)]
+#[CoversTrait(DispatchesContextualization::class)]
 final class AbstractPlatformTest extends EnvironmentDetectorTestCase {
 
   public function testIdDefaultsToConst(): void {

tests/Stacks/AbstractStackTest.php

@@ -6,12 +6,15 @@
 
 use DrevOps\EnvironmentDetector\Contexts\Drupal;
 use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
+use DrevOps\EnvironmentDetector\DispatchesContextualization;
 use DrevOps\EnvironmentDetector\Stacks\AbstractStack;
 use DrevOps\EnvironmentDetector\Tests\EnvironmentDetectorTestCase;
 use DrevOps\EnvironmentDetector\Tests\Fixtures\NotDrupalContext;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversTrait;
 
 #[CoversClass(AbstractStack::class)]
+#[CoversTrait(DispatchesContextualization::class)]
 final class AbstractStackTest extends EnvironmentDetectorTestCase {
 
   public function testIdDefaultsToConst(): void {