Added Production/Development environment

Author: WalterWoshid

src/CodeTransformerKernel.php

@@ -9,6 +9,7 @@
 use Okapi\CodeTransformer\Core\DI;
 use Okapi\CodeTransformer\Core\Exception\Kernel\DirectKernelInitializationException;
 use Okapi\CodeTransformer\Core\Options;
+use Okapi\CodeTransformer\Core\Options\Environment;
 use Okapi\CodeTransformer\Core\StreamFilter;
 use Okapi\Singleton\Singleton;
 
@@ -18,9 +19,12 @@
  * This class is the heart of the Code Transformer library.
  * It manages an environment for Code Transformation.
  *
- * 1. Extends this class and define a list of transformers in the
- *    `$transformers` property.
- * 2. Call the `init()` method early in the application lifecycle.
+ * 1. Extend this class and define a list of transformers in the
+ *    {@link $transformers} property.
+ * 2. Call the {@link init()} method early in the application lifecycle.
+ *
+ * If you want to modify the kernel options dynamically, override the
+ * {@link configureOptions()} method.
  */
 abstract class CodeTransformerKernel
 {
@@ -80,6 +84,19 @@ public function __construct() {}
      */
     protected bool $debug = false;
 
+    /**
+     * The environment in which the application is running.
+     * <br><b>Default:</b> {@link Environment::DEVELOPMENT}<br><br>
+     *
+     * If {@link Environment::PRODUCTION}, the cache will not be checked for
+     *   updates (better performance).<br>
+     * If {@link Environment::DEVELOPMENT}, the cache will be checked for
+     *   updates (better development experience).
+     *
+     * @var Environment
+     */
+    protected Environment $environment = Environment::DEVELOPMENT;
+
     /**
      * Throw an exception if the kernel is initialized twice.
      * <br><b>Default:</b> {@link false}<br>
@@ -163,6 +180,7 @@ protected function preInit(): void
             cacheDir:      $this->cacheDir,
             cacheFileMode: $this->cacheFileMode,
             debug:         $this->debug,
+            environment:   $this->environment,
         );
 
         // Add the transformers

src/Core/AutoloadInterceptor/ClassLoader.php

@@ -8,6 +8,7 @@
 use Okapi\CodeTransformer\Core\Cache\CacheStateManager;
 use Okapi\CodeTransformer\Core\Matcher\TransformerMatcher;
 use Okapi\CodeTransformer\Core\Options;
+use Okapi\CodeTransformer\Core\Options\Environment;
 use Okapi\CodeTransformer\Core\StreamFilter;
 use Okapi\CodeTransformer\Core\StreamFilter\FilterInjector;
 use Okapi\Path\Path;
@@ -108,13 +109,28 @@ public function findFile($namespacedClass): false|string
         // Query cache state
         $cacheState = $this->cacheStateManager->queryCacheState($filePath);
 
-        // Check if the file is cached and up to date
-        if ($cacheState?->isFresh() && !$this->options->isDebug()) {
+        // When debugging, bypass the caching mechanism
+        if ($this->options->isDebug()) {
+            // ...
+        }
+
+        // In production mode, use the cache without checking if it is fresh
+        elseif ($this->options->getEnvironment() === Environment::PRODUCTION
+            && $cacheState
+        ) {
             // Use the cached file if transformations have been applied
             // Or return the original file if no transformations have been applied
             return $cacheState->getFilePath() ?? $filePath;
         }
 
+        // In development mode, check if the cache is fresh
+        elseif ($this->options->getEnvironment() === Environment::DEVELOPMENT
+            && $cacheState
+            && $cacheState->isFresh()
+        ) {
+            return $cacheState->getFilePath() ?? $filePath;
+        }
+
 
         // Check if the class should be transformed
         if (!$this->transformerMatcher->match($namespacedClass, $filePath)) {

src/Core/Options.php

@@ -4,6 +4,7 @@
 
 use Composer\Autoload\ClassLoader;
 use Okapi\CodeTransformer\CodeTransformerKernel;
+use Okapi\CodeTransformer\Core\Options\Environment;
 use Okapi\Path\Path;
 use ReflectionClass;
 
@@ -45,6 +46,13 @@ class Options implements ServiceInterface
      */
     private bool $debug;
 
+    /**
+     * The environment in which the application is running.
+     *
+     * @var Environment
+     */
+    private Environment $environment;
+
     // endregion
 
     /**
@@ -63,12 +71,14 @@ class Options implements ServiceInterface
      *
      * @param string|null $cacheDir
      * @param int|null    $cacheFileMode
-     * @param bool|null   $debug
+     * @param bool        $debug
+     * @param Environment $environment
      */
     public function setOptions(
-        ?string $cacheDir,
-        ?int    $cacheFileMode,
-        ?bool   $debug,
+        ?string     $cacheDir,
+        ?int        $cacheFileMode,
+        bool        $debug,
+        Environment $environment,
     ): void {
         $composerRef = new ReflectionClass(ClassLoader::class);
         $composerDir = $composerRef->getFileName();
@@ -77,7 +87,8 @@ public function setOptions(
         $this->appDir        = $rootDir;
         $this->cacheDir      = $cacheDir ?? Path::join($rootDir, $this->defaultCacheDir);
         $this->cacheFileMode = $cacheFileMode ?? (0777 & ~umask());
-        $this->debug         = $debug ?? false;
+        $this->debug         = $debug;
+        $this->environment   = $environment;
     }
 
     // endregion
@@ -125,4 +136,12 @@ public function isDebug(): bool
     {
         return $this->debug;
     }
+
+    /**
+     * Get the environment in which the application is running.
+     */
+    public function getEnvironment(): Environment
+    {
+        return $this->environment;
+    }
 }

src/Core/Options/Environment.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Okapi\CodeTransformer\Core\Options;
+
+/**
+ * # Environment
+ *
+ * The environment in which the application is running.
+ */
+enum Environment
+{
+    /**
+     * Cache will not be checked for updates (better performance).
+     */
+    case PRODUCTION;
+
+    /**
+     * Cache will be checked for updates (better development experience).
+     */
+    case DEVELOPMENT;
+}