feat: allow object to define how they are mapped to array (#532)

Author: aidan-casey

composer.json

@@ -1,12 +1,13 @@
 {
     "name": "tempest/core",
+    "description": "The core component of the Tempest framework.",
     "license": "MIT",
     "minimum-stability": "dev",
     "require": {
         "php": "^8.3",
-        "tempest/container": "self.version",
+        "tempest/container": "dev-main",
         "vlucas/phpdotenv": "^5.6",
-        "spatie/ignition": "^1.15",
+        "filp/whoops": "^2.15",
         "nunomaduro/collision": "^8.4"
     },
     "autoload": {

phpunit.xml

@@ -1,20 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         executionOrder="depends,defects"
-         beStrictAboutOutputDuringTests="true"
-         displayDetailsOnPhpunitDeprecations="true"
-         failOnPhpunitDeprecation="true"
-         failOnRisky="true"
-         failOnWarning="true">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.4/phpunit.xsd" bootstrap="vendor/autoload.php" executionOrder="depends,defects" beStrictAboutOutputDuringTests="true" displayDetailsOnPhpunitDeprecations="true" failOnPhpunitDeprecation="false" failOnRisky="true" failOnWarning="true">
     <testsuites>
         <testsuite name="Tempest Core">
             <directory>tests</directory>
         </testsuite>
     </testsuites>
-
-    <source restrictDeprecations="true" restrictNotices="true" restrictWarnings="true">
+    <source restrictNotices="true" restrictWarnings="true" ignoreIndirectDeprecations="true">
         <include>
             <directory>src</directory>
         </include>

src/AppConfig.php

@@ -6,14 +6,24 @@
 
 final class AppConfig
 {
+    public Environment $environment;
+
+    public string $baseUri;
+
     public function __construct(
-        public Environment $environment = Environment::LOCAL,
+        ?Environment $environment = null,
+        ?string $baseUri = null,
         public ExceptionHandlerSetup $exceptionHandlerSetup = new GenericExceptionHandlerSetup(),
 
         /** @var \Tempest\Core\ExceptionHandler[] */
         public array $exceptionHandlers = [
             // …,
         ],
     ) {
+        $this->environment = $environment
+            ?? Environment::tryFrom(\Tempest\env('ENVIRONMENT', 'local'))
+            ?? Environment::LOCAL;
+
+        $this->baseUri = $baseUri ?? \Tempest\env('BASE_URI') ?? '';
     }
 }

src/Composer.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Core;
+
+use function Tempest\Support\arr;
+use Tempest\Support\PathHelper;
+
+final readonly class Composer
+{
+    /** @var array<ComposerNamespace> */
+    public array $namespaces;
+
+    public ?ComposerNamespace $mainNamespace;
+
+    public array $composer;
+
+    public function __construct(
+        string $root,
+    ) {
+        $composerFilePath = PathHelper::make($root, 'composer.json');
+
+        $this->composer = $this->loadComposerFile($composerFilePath);
+        $this->namespaces = arr($this->composer)
+            ->get('autoload.psr-4', default: arr())
+            ->map(fn (string $path, string $namespace) => new ComposerNamespace($namespace, $path))
+            ->values()
+            ->toArray();
+
+        foreach ($this->namespaces as $namespace) {
+            if (str_starts_with($namespace->path, 'app/') || str_starts_with($namespace->path, 'src/')) {
+                $this->mainNamespace = $namespace;
+
+                break;
+            }
+        }
+
+        if (! isset($this->mainNamespace) && count($this->namespaces)) {
+            $this->mainNamespace = $this->namespaces[0];
+        }
+
+        if (! isset($this->mainNamespace)) {
+            throw new KernelException("Tempest requires at least one PSR-4 namespace to be defined in composer.json.");
+        }
+    }
+
+    private function loadComposerFile(string $path): array
+    {
+        if (! file_exists($path)) {
+            throw new KernelException("Could not locate composer.json.");
+        }
+
+        return json_decode(file_get_contents($path), associative: true);
+    }
+}

src/ComposerNamespace.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Core;
+
+final readonly class ComposerNamespace
+{
+    public function __construct(
+        public string $namespace,
+        public string $path,
+    ) {
+    }
+}

src/DiscoveryDiscovery.php

@@ -9,7 +9,7 @@
 
 final readonly class DiscoveryDiscovery implements Discovery
 {
-    public const string CACHE_PATH = __DIR__ . '/../../../.cache/tempest/discovery-discovery.cache.php';
+    public const string CACHE_PATH = __DIR__ . '/../../../../.cache/tempest/discovery-discovery.cache.php';
 
     public function __construct(
         private Kernel $kernel,

src/DoNotDiscover.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Core;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final class DoNotDiscover
+{
+    public function __construct(
+        /**
+         * Allows the specified `Discovery` classes to still discover this class.
+         * @var array<class-string<\Tempest\Core\Discovery>>
+         */
+        public readonly array $except = [],
+    ) {
+    }
+}

src/GenericExceptionHandlerSetup.php

@@ -5,34 +5,72 @@
 namespace Tempest\Core;
 
 use NunoMaduro\Collision\Provider as Collision;
-use Spatie\Ignition\Ignition;
+use Throwable;
+use Whoops\Handler\PrettyPageHandler;
+use Whoops\Run;
 
 final readonly class GenericExceptionHandlerSetup implements ExceptionHandlerSetup
 {
     public function setup(AppConfig $appConfig): void
     {
+        if ($appConfig->environment->isTesting()) {
+            return;
+        }
+
         // Console
-        if ($_SERVER['argv'] ?? null) {
+        if (PHP_SAPI === 'cli') {
             (new Collision())->register();
 
             return;
         }
 
         // Production web
         if ($appConfig->environment->isProduction()) {
-            set_exception_handler($this->renderErrorPage(...));
-            /** @phpstan-ignore-next-line  */
+            set_exception_handler($this->renderExceptionPage(...));
+            /** @phpstan-ignore-next-line */
             set_error_handler($this->renderErrorPage(...));
 
             return;
         }
 
-        // Production dev
-        Ignition::make()->register();
+        // Local web
+        $whoops = new Run();
+        $whoops->pushHandler(new PrettyPageHandler());
+        $whoops->register();
     }
 
-    public function renderErrorPage(): void
+    public function renderExceptionPage(Throwable $throwable): void
     {
+        ll($throwable);
+
+        ob_start();
+
+        if (! headers_sent()) {
+            http_response_code(500);
+        }
+
+        echo file_get_contents(__DIR__ . '/500.html');
+
+        ob_end_flush();
+
+        exit;
+    }
+
+    public function renderErrorPage(
+        int $errNo,
+        string $errstr,
+        string $errFile,
+        int $errLine,
+    ): void {
+        ll("{$errFile}:{$errLine} {$errstr} ({$errNo})");
+
+        if (
+            $errNo === E_USER_WARNING
+            || $errNo === E_DEPRECATED
+        ) {
+            return;
+        }
+
         ob_start();
 
         if (! headers_sent()) {

src/HandlesDiscoveryCache.php

@@ -15,7 +15,7 @@ public function getCachePath(): string
 
         $name = array_pop($parts) . '.cache.php';
 
-        return __DIR__ . '/../../../.cache/tempest/' . $name;
+        return __DIR__ . '/../../../../.cache/tempest/' . $name;
     }
 
     abstract public function createCachePayload(): string;

src/Kernel.php

@@ -36,11 +36,12 @@ public function __construct(
             ->setDiscoveryCache($discoveryCache)
             ->registerShutdownFunction()
             ->registerKernel()
+            ->loadComposer()
             ->loadDiscoveryLocations()
             ->loadConfig()
-            ->loadDiscovery();
-
-        $this->container->get(EventBus::class)->dispatch(KernelEvent::BOOTED);
+            ->loadExceptionHandler()
+            ->loadDiscovery()
+            ->event(KernelEvent::BOOTED);
     }
 
     public static function boot(string $root, ?Container $container = null): self
@@ -62,6 +63,13 @@ private function createContainer(): Container
         return $container;
     }
 
+    private function loadComposer(): self
+    {
+        $this->container->singleton(Composer::class, new Composer($this->root));
+
+        return $this;
+    }
+
     private function loadEnv(): self
     {
         $dotenv = Dotenv::createUnsafeImmutable($this->root);
@@ -126,4 +134,22 @@ private function loadConfig(): self
 
         return $this;
     }
+
+    private function loadExceptionHandler(): self
+    {
+        $appConfig = $this->container->get(AppConfig::class);
+
+        $appConfig->exceptionHandlerSetup->setup($appConfig);
+
+        return $this;
+    }
+
+    private function event(object $event): self
+    {
+        if (interface_exists(EventBus::class)) {
+            $this->container->get(EventBus::class)->dispatch($event);
+        }
+
+        return $this;
+    }
 }

src/Kernel/LoadDiscoveryClasses.php

@@ -7,10 +7,12 @@
 use FilesystemIterator;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
+use ReflectionException;
 use SplFileInfo;
 use Tempest\Container\Container;
 use Tempest\Core\DiscoversPath;
 use Tempest\Core\Discovery;
+use Tempest\Core\DoNotDiscover;
 use Tempest\Core\Kernel;
 use Tempest\Reflection\ClassReflector;
 use Throwable;
@@ -32,11 +34,15 @@ public function __invoke(): void
             /** @var Discovery $discovery */
             $discovery = $this->container->get($discoveryClass);
 
-            if ($this->kernel->discoveryCache && $discovery->hasCache()) {
-                $discovery->restoreCache($this->container);
-                next($this->kernel->discoveryClasses);
+            try {
+                if ($this->kernel->discoveryCache && $discovery->hasCache()) {
+                    $discovery->restoreCache($this->container);
+                    next($this->kernel->discoveryClasses);
 
-                continue;
+                    continue;
+                }
+            } catch (ReflectionException) {
+                // Invalid cache
             }
 
             foreach ($this->kernel->discoveryLocations as $discoveryLocation) {
@@ -90,7 +96,9 @@ public function __invoke(): void
                     }
 
                     if ($input instanceof ClassReflector) {
-                        $discovery->discover($input);
+                        if ($this->shouldDiscover($discovery, $input)) {
+                            $discovery->discover($input);
+                        }
                     } elseif ($discovery instanceof DiscoversPath) {
                         $discovery->discoverPath($input);
                     }
@@ -104,4 +112,13 @@ public function __invoke(): void
             }
         }
     }
+
+    private function shouldDiscover(Discovery $discovery, ClassReflector $input): bool
+    {
+        if (is_null($attribute = $input->getAttribute(DoNotDiscover::class))) {
+            return true;
+        }
+
+        return in_array($discovery::class, $attribute->except, strict: true);
+    }
 }