Centralize runtime environment checks

Author: coisa

src/Console/Output/GithubActionOutput.php

@@ -19,7 +19,7 @@
 
 namespace FastForward\DevTools\Console\Output;
 
-use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use Symfony\Component\Console\Output\ConsoleOutputInterface;
 
 /**
@@ -35,11 +35,11 @@ final class GithubActionOutput
 
     /**
      * @param ConsoleOutputInterface $output the console output used to emit workflow commands
-     * @param EnvironmentInterface $environment reads runtime environment flags
+     * @param RuntimeEnvironmentInterface $environment resolves runtime environment capabilities
      */
     public function __construct(
         private readonly ConsoleOutputInterface $output,
-        private readonly EnvironmentInterface $environment,
+        private readonly RuntimeEnvironmentInterface $environment,
     ) {}
 
     /**
@@ -247,22 +247,8 @@ private function emit(string $command, string $message = '', array $properties =
      */
     private function supportsWorkflowCommands(): bool
     {
-        return $this->isTruthyEnvironmentFlag('GITHUB_ACTIONS')
-            && ! $this->isTruthyEnvironmentFlag('COMPOSER_TESTS_ARE_RUNNING');
-    }
-
-    /**
-     * Determines whether an environment flag is set to a truthy value.
-     *
-     * @param string $name the environment variable name
-     *
-     * @return bool true when the environment variable is truthy
-     */
-    private function isTruthyEnvironmentFlag(string $name): bool
-    {
-        $value = $this->environment->get($name, '');
-
-        return null !== $value && '' !== $value && '0' !== $value;
+        return $this->environment->isGithubActions()
+            && ! $this->environment->isComposerTestRun();
     }
 
     /**

src/Environment/RuntimeEnvironment.php

@@ -0,0 +1,71 @@
+<?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\Environment;
+
+/**
+ * Resolves common runtime-environment flags used by DevTools integrations.
+ */
+final readonly class RuntimeEnvironment implements RuntimeEnvironmentInterface
+{
+    /**
+     * @param EnvironmentInterface $environment reads raw process environment variables
+     */
+    public function __construct(
+        private EnvironmentInterface $environment,
+    ) {}
+
+    /**
+     * Returns whether a truthy environment flag is enabled.
+     *
+     * @param string $name the environment variable name
+     */
+    public function isEnabled(string $name): bool
+    {
+        return \in_array(strtolower((string) $this->environment->get($name, '')), ['1', 'true', 'yes', 'on'], true);
+    }
+
+    /**
+     * Returns whether the current process runs in GitHub Actions.
+     */
+    public function isGithubActions(): bool
+    {
+        return $this->isEnabled('GITHUB_ACTIONS');
+    }
+
+    /**
+     * Returns whether the current process runs in a CI environment.
+     */
+    public function isCi(): bool
+    {
+        if ($this->isGithubActions()) {
+            return true;
+        }
+
+        return $this->isEnabled('CI');
+    }
+
+    /**
+     * Returns whether the Composer test suite runtime flag is enabled.
+     */
+    public function isComposerTestRun(): bool
+    {
+        return $this->isEnabled('COMPOSER_TESTS_ARE_RUNNING');
+    }
+}

src/Environment/RuntimeEnvironmentInterface.php

@@ -0,0 +1,50 @@
+<?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\Environment;
+
+/**
+ * Answers common runtime-environment questions from process environment flags.
+ */
+interface RuntimeEnvironmentInterface
+{
+    /**
+     * Returns whether a truthy environment flag is enabled.
+     *
+     * @param string $name the environment variable name
+     *
+     * @return bool true when the environment variable is enabled
+     */
+    public function isEnabled(string $name): bool;
+
+    /**
+     * Returns whether the current process runs in GitHub Actions.
+     */
+    public function isGithubActions(): bool;
+
+    /**
+     * Returns whether the current process runs in a CI environment.
+     */
+    public function isCi(): bool;
+
+    /**
+     * Returns whether the Composer test suite runtime flag is enabled.
+     */
+    public function isComposerTestRun(): bool;
+}

src/Process/ProcessQueue.php

@@ -22,7 +22,7 @@
 use Closure;
 use FastForward\DevTools\Console\Output\GithubActionOutput;
 use FastForward\DevTools\Console\Output\OutputCapabilityDetectorInterface;
-use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use ReflectionProperty;
 use Symfony\Component\Console\Input\ArrayInput;
 use Symfony\Component\Console\Output\ConsoleOutputInterface;
@@ -73,13 +73,13 @@ final class ProcessQueue implements ProcessQueueInterface
     /**
      * @param GithubActionOutput $githubActionOutput wraps grouped queue output in GitHub Actions logs when supported
      * @param ProcessEnvironmentConfiguratorInterface $environmentConfigurator
-     * @param EnvironmentInterface $environment reads runtime environment flags
+     * @param RuntimeEnvironmentInterface $environment resolves runtime environment capabilities
      * @param OutputCapabilityDetectorInterface $outputCapabilityDetector detects ANSI-capable output
      */
     public function __construct(
         private readonly GithubActionOutput $githubActionOutput,
         private readonly ProcessEnvironmentConfiguratorInterface $environmentConfigurator,
-        private readonly EnvironmentInterface $environment,
+        private readonly RuntimeEnvironmentInterface $environment,
         private readonly OutputCapabilityDetectorInterface $outputCapabilityDetector,
     ) {}
 
@@ -404,7 +404,7 @@ private function runInOutputSection(string $label, OutputInterface $output, Clos
     private function shouldRenderLocalSection(OutputInterface $output): bool
     {
         return $this->outputCapabilityDetector->supportsAnsi($output)
-            && null === $this->environment->get('GITHUB_ACTIONS');
+            && ! $this->environment->isGithubActions();
     }
 
     /**

src/SelfUpdate/VersionCheckNotifier.php

@@ -19,7 +19,7 @@
 
 namespace FastForward\DevTools\SelfUpdate;
 
-use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use Throwable;
 use Symfony\Component\Console\Output\OutputInterface;
 
@@ -30,11 +30,11 @@
 {
     /**
      * @param VersionCheckerInterface $versionChecker the checker used to resolve latest release metadata
-     * @param EnvironmentInterface $environment the environment reader used to skip non-interactive CI checks
+     * @param RuntimeEnvironmentInterface $environment resolves runtime environment capabilities
      */
     public function __construct(
         private VersionCheckerInterface $versionChecker,
-        private EnvironmentInterface $environment,
+        private RuntimeEnvironmentInterface $environment,
     ) {}
 
     /**
@@ -70,22 +70,10 @@ public function notify(OutputInterface $output): void
      */
     private function shouldSkipVersionCheck(): bool
     {
-        foreach (['FAST_FORWARD_SKIP_VERSION_CHECK', 'GITHUB_ACTIONS', 'CI'] as $name) {
-            if ($this->isTruthy($this->environment->get($name, ''))) {
-                return true;
-            }
+        if ($this->environment->isCi()) {
+            return true;
         }
 
-        return false;
-    }
-
-    /**
-     * Returns whether an environment value represents an enabled flag.
-     *
-     * @param string|null $value the environment value to inspect
-     */
-    private function isTruthy(?string $value): bool
-    {
-        return \in_array(strtolower((string) $value), ['1', 'true', 'yes', 'on'], true);
+        return $this->environment->isEnabled('FAST_FORWARD_SKIP_VERSION_CHECK');
     }
 }

src/ServiceProvider/DevToolsServiceProvider.php

@@ -45,6 +45,8 @@
 use FastForward\DevTools\Console\Output\OutputCapabilityDetectorInterface;
 use FastForward\DevTools\Environment\Environment;
 use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironment;
+use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use FastForward\DevTools\Filesystem\FinderFactory;
 use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use FastForward\DevTools\Filesystem\Filesystem;
@@ -132,6 +134,7 @@ public function getFactories(): array
         return [
             // Process
             EnvironmentInterface::class => get(Environment::class),
+            RuntimeEnvironmentInterface::class => get(RuntimeEnvironment::class),
             ExtensionInterface::class => get(Extension::class),
             OutputCapabilityDetectorInterface::class => get(OutputCapabilityDetector::class),
             ProcessBuilderInterface::class => get(ProcessBuilder::class),
@@ -186,7 +189,7 @@ public function getFactories(): array
                 ->method('setFormatter', get(LogLevelOutputFormatter::class)),
             GithubActionOutput::class => create(GithubActionOutput::class)->constructor(
                 get(ConsoleOutputInterface::class),
-                get(EnvironmentInterface::class)
+                get(RuntimeEnvironmentInterface::class)
             ),
             ContextProcessorInterface::class => create(CompositeContextProcessor::class)->constructor([
                 get(CommandInputProcessor::class),

tests/Console/DevToolsTest.php

@@ -25,6 +25,7 @@
 use FastForward\DevTools\Console\Formatter\LogLevelOutputFormatter;
 use FastForward\DevTools\Console\Output\GithubActionOutput;
 use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironment;
 use FastForward\DevTools\Filesystem\FinderFactory;
 use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Path\WorkingProjectPathResolver;
@@ -70,6 +71,7 @@
 #[UsesClass(ClassReflection::class)]
 #[UsesClass(LogLevelOutputFormatter::class)]
 #[UsesClass(GithubActionOutput::class)]
+#[UsesClass(RuntimeEnvironment::class)]
 #[UsesClass(ColorPreservingProcessEnvironmentConfigurator::class)]
 #[UsesClass(CompositeProcessEnvironmentConfigurator::class)]
 #[UsesClass(ProcessBuilder::class)]

tests/Console/Logger/OutputFormatLoggerTest.php

@@ -27,7 +27,7 @@
 use FastForward\DevTools\Console\Logger\Processor\CommandOutputProcessor;
 use FastForward\DevTools\Console\Logger\Processor\CompositeContextProcessor;
 use FastForward\DevTools\Console\Output\GithubActionOutput;
-use FastForward\DevTools\Environment\EnvironmentInterface;
+use FastForward\DevTools\Environment\RuntimeEnvironmentInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -59,7 +59,7 @@ final class OutputFormatLoggerTest extends TestCase
     private ObjectProphecy $clock;
 
     /**
-     * @var ObjectProphecy<EnvironmentInterface>
+     * @var ObjectProphecy<RuntimeEnvironmentInterface>
      */
     private ObjectProphecy $environment;
 
@@ -83,9 +83,9 @@ protected function setUp(): void
         $this->output = $this->prophesize(ConsoleOutputInterface::class);
         $this->errorOutput = $this->prophesize(OutputInterface::class);
         $this->clock = $this->prophesize(ClockInterface::class);
-        $this->environment = $this->prophesize(EnvironmentInterface::class);
-        $this->environment->get(Argument::type('string'), Argument::cetera())
-            ->willReturn(null);
+        $this->environment = $this->prophesize(RuntimeEnvironmentInterface::class);
+        $this->environment->isGithubActions()
+            ->willReturn(false);
 
         $this->output->getErrorOutput()
             ->willReturn($this->errorOutput->reveal());