[container] Centralize trait-only service resolution

Author: coisa

src/Console/Command/TestsCommand.php

@@ -24,7 +24,6 @@
 use FastForward\DevTools\Console\Input\HasCacheOption;
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use FastForward\DevTools\Composer\Json\ComposerJsonInterface;
-use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\PhpUnit\Bootstrap\BootstrapShimGenerator;
@@ -34,7 +33,6 @@
 use FastForward\DevTools\Path\ManagedWorkspace;
 use FastForward\DevTools\Project\ProjectCapabilitiesResolverInterface;
 use InvalidArgumentException;
-use Psr\Log\LoggerInterface;
 use Psr\Log\LogLevel;
 use RuntimeException;
 use Symfony\Component\Config\FileLocatorInterface;
@@ -82,8 +80,6 @@ final class TestsCommand extends Command
      * @param ProcessBuilderInterface $processBuilder the builder used to assemble the PHPUnit process
      * @param ProcessQueueInterface $processQueue the queue used to execute PHPUnit
      * @param ProjectCapabilitiesResolverInterface $projectCapabilitiesResolver the project capability resolver
-     * @param RuntimeEnvironmentInterface $runtimeEnvironment the runtime environment capability resolver
-     * @param LoggerInterface $logger the output-aware logger
      */
     public function __construct(
         private readonly CoverageSummaryLoaderInterface $coverageSummaryLoader,
@@ -94,8 +90,6 @@ public function __construct(
         private readonly ProcessBuilderInterface $processBuilder,
         private readonly ProcessQueueInterface $processQueue,
         private readonly ProjectCapabilitiesResolverInterface $projectCapabilitiesResolver,
-        private readonly RuntimeEnvironmentInterface $runtimeEnvironment,
-        private readonly LoggerInterface $logger,
     ) {
         parent::__construct();
     }

src/Console/Command/Traits/HasCommandLogger.php

@@ -19,15 +19,16 @@
 
 namespace FastForward\DevTools\Console\Command\Traits;
 
+use FastForward\DevTools\Container\ContainerFactory;
 use LogicException;
 use Psr\Log\LoggerInterface;
 
 /**
  * Resolves the logger expected by command result helper traits.
  *
- * The consuming command is expected to expose an initialized `$logger`
- * property so reusable traits can log without coupling themselves to a
- * specific constructor signature.
+ * The consuming command MAY expose an initialized `$logger` property. When it
+ * does not, the trait SHALL resolve the shared logger from the DevTools
+ * container so reusable traits can stay decoupled from constructor wiring.
  */
 trait HasCommandLogger
 {
@@ -38,22 +39,28 @@ trait HasCommandLogger
      */
     public function getLogger(): LoggerInterface
     {
-        if (! property_exists($this, 'logger') || null === $this->logger) {
+        if (property_exists($this, 'logger') && $this->logger instanceof LoggerInterface) {
+            return $this->logger;
+        }
+
+        if (property_exists($this, 'logger') && null !== $this->logger) {
             throw new LogicException(\sprintf(
-                'Commands using %s MUST expose an initialized $logger property with an instance of %s.',
+                'Commands using %s MUST expose a %s instance on the $logger property.',
                 LogsCommandResults::class,
                 LoggerInterface::class,
             ));
         }
 
-        if (! $this->logger instanceof LoggerInterface) {
+        $logger = ContainerFactory::get(LoggerInterface::class);
+
+        if (! $logger instanceof LoggerInterface) {
             throw new LogicException(\sprintf(
-                'Commands using %s MUST expose a %s instance on the $logger property.',
+                'Commands using %s MUST resolve a %s instance from the shared container.',
                 LogsCommandResults::class,
                 LoggerInterface::class,
             ));
         }
 
-        return $this->logger;
+        return $logger;
     }
 }

src/Console/DevTools.php

@@ -20,15 +20,14 @@
 namespace FastForward\DevTools\Console;
 
 use FastForward\DevTools\Console\Command\SelfUpdateCommand;
+use FastForward\DevTools\Container\ContainerFactory;
 use FastForward\DevTools\Environment\EnvironmentInterface;
 use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
 use FastForward\DevTools\SelfUpdate\SelfUpdateRunnerInterface;
 use FastForward\DevTools\SelfUpdate\SelfUpdateScopeResolverInterface;
 use FastForward\DevTools\SelfUpdate\VersionCheckNotifierInterface;
 use FastForward\DevTools\SelfUpdate\WorkingDirectorySwitcherInterface;
-use FastForward\DevTools\ServiceProvider\DevToolsServiceProvider;
-use DI\Container;
 use Override;
 use Psr\Container\ContainerInterface;
 use Symfony\Component\Console\Application;
@@ -65,11 +64,6 @@ final class DevTools extends Application
      */
     private const array RAW_OUTPUT_COMMANDS = ['changelog:next-version', 'changelog:show'];
 
-    /**
-     * @var ContainerInterface holds the static container instance for global access within the DevTools context
-     */
-    private static ?ContainerInterface $container = null;
-
     /**
      * Initializes the DevTools global context and dependency graph.
      *
@@ -177,20 +171,15 @@ public function doRun(InputInterface $input, OutputInterface $output): int
      */
     public static function create(): self
     {
-        return self::getContainer()->get(self::class);
+        return ContainerFactory::get(self::class);
     }
 
     /**
      * Retrieves the shared DevTools service container.
      */
     public static function getContainer(): ContainerInterface
     {
-        if (! self::$container instanceof ContainerInterface) {
-            $serviceProvider = new DevToolsServiceProvider();
-            self::$container = new Container($serviceProvider->getFactories());
-        }
-
-        return self::$container;
+        return ContainerFactory::create();
     }
 
     /**

src/Console/Input/HasJsonOption.php

@@ -19,7 +19,7 @@
 
 namespace FastForward\DevTools\Console\Input;
 
-use Ergebnis\AgentDetector\Detector;
+use FastForward\DevTools\Container\ContainerFactory;
 use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -80,22 +80,21 @@ protected function isPrettyJsonOutput(InputInterface $input): bool
      *
      * Commands MAY opt into runtime-environment-aware behavior by exposing a
      * `$runtimeEnvironment` property. Commands that do not expose it SHALL fall
-     * back to lightweight agent detection based on process environment
-     * variables, except while the PHPUnit test runtime is active.
+     * back to the shared runtime-environment service from the DevTools container.
      */
     private function isImplicitJsonOutputEnabled(): bool
     {
         $runtimeEnvironment = $this->resolveRuntimeEnvironment();
 
-        if ($runtimeEnvironment instanceof RuntimeEnvironmentInterface) {
-            return $runtimeEnvironment->isAgentPresent() && ! $runtimeEnvironment->isComposerTestRun();
+        if (! $runtimeEnvironment instanceof RuntimeEnvironmentInterface) {
+            $runtimeEnvironment = ContainerFactory::get(RuntimeEnvironmentInterface::class);
         }
 
-        if ($this->isPhpUnitRuntime() || $this->isComposerTestRunEnvironmentEnabled()) {
+        if (! $runtimeEnvironment instanceof RuntimeEnvironmentInterface) {
             return false;
         }
 
-        return (new Detector())->isAgentPresent($this->resolveEnvironmentVariables());
+        return $runtimeEnvironment->isAgentPresent() && ! $runtimeEnvironment->isComposerTestRun();
     }
 
     /**
@@ -113,48 +112,4 @@ private function resolveRuntimeEnvironment(): ?RuntimeEnvironmentInterface
 
         return $this->runtimeEnvironment;
     }
-
-    /**
-     * Returns whether the current process is executing inside PHPUnit.
-     */
-    private function isPhpUnitRuntime(): bool
-    {
-        return \defined('PHPUNIT_COMPOSER_INSTALL');
-    }
-
-    /**
-     * Returns whether the Composer test runtime flag is enabled.
-     */
-    private function isComposerTestRunEnvironmentEnabled(): bool
-    {
-        $value = $_SERVER['COMPOSER_TESTS_ARE_RUNNING'] ?? getenv('COMPOSER_TESTS_ARE_RUNNING');
-
-        if (false === $value || null === $value) {
-            return false;
-        }
-
-        return \in_array(strtolower((string) $value), ['1', 'true', 'yes', 'on'], true);
-    }
-
-    /**
-     * Returns environment variables suitable for lightweight agent detection.
-     *
-     * @return array<string, string>
-     */
-    private function resolveEnvironmentVariables(): array
-    {
-        $environmentVariables = [];
-
-        foreach ([$_SERVER, $_ENV] as $environment) {
-            foreach ($environment as $name => $value) {
-                if (! \is_string($name) || ! \is_string($value)) {
-                    continue;
-                }
-
-                $environmentVariables[$name] ??= $value;
-            }
-        }
-
-        return $environmentVariables;
-    }
 }

src/Container/ContainerFactory.php

@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Container;
+
+use DI\Container;
+use FastForward\DevTools\Container\ServiceProvider\DevToolsServiceProvider;
+use Psr\Container\ContainerInterface;
+
+/**
+ * Builds and caches the shared DevTools dependency injection container.
+ *
+ * The factory centralizes container bootstrapping so command traits and other
+ * internal helpers can resolve services without duplicating bootstrap logic or
+ * depending on the console application entrypoint.
+ */
+final class ContainerFactory
+{
+    private static ?Container $container = null;
+
+    /**
+     * Creates or returns the shared DevTools container instance.
+     *
+     * @return ContainerInterface the shared container instance
+     */
+    public static function create(): ContainerInterface
+    {
+        if (! self::$container instanceof Container) {
+            $serviceProvider = new DevToolsServiceProvider();
+            self::$container = new Container($serviceProvider->getFactories());
+        }
+
+        return self::$container;
+    }
+
+    /**
+     * Resolves a service from the shared DevTools container.
+     *
+     * @template T
+     *
+     * @param string|class-string<T> $id the service identifier
+     *
+     * @return mixed|T the resolved service
+     */
+    public static function get(string $id): mixed
+    {
+        return self::create()->get($id);
+    }
+
+    /**
+     * Returns whether the shared DevTools container can resolve a service.
+     *
+     * @param string $id the service identifier
+     */
+    public static function has(string $id): bool
+    {
+        return self::create()->has($id);
+    }
+
+    /**
+     * Overrides a shared service entry for the current process.
+     *
+     * @internal this method exists so tests can replace container entries with doubles
+     *
+     * @param string $id the service identifier
+     * @param mixed $value the replacement service entry
+     */
+    public static function set(string $id, mixed $value): void
+    {
+        self::create();
+        self::$container?->set($id, $value);
+    }
+
+    /**
+     * Resets the cached shared container instance.
+     *
+     * @internal this method exists so tests can isolate container state between test cases
+     */
+    public static function reset(): void
+    {
+        self::$container = null;
+    }
+}