feat(discovery): skip discovery with closure (#2070)

Author: brendt

docs/1-essentials/05-discovery.md

@@ -306,6 +306,44 @@ new BootDiscovery(
 )();
 ```
 
+You can also mark classes themselves to be skipped entirely by discovery:
+
+```php
+use Tempest\Discovery\SkipDiscovery;
+
+#[SkipDiscovery]
+final readonly class CautionMiddleware implements ConsoleMiddleware
+{
+    // …
+}
+```
+
+Furthermore, you can skip discovery entirely for a specific class, expect for a specific set of discovery classes:
+
+```php
+use Tempest\Discovery\SkipDiscovery;
+
+#[SkipDiscovery(except: [MigrationDiscovery::class])]
+final class HiddenMigratableDatabaseMigration implements MigratesUp
+{
+    // …
+}
+```
+
+Finally, you can pass in a callable to this `$except` parameter as well, which allows access to the container, and gives you even more flexibility on when a class should be skipped or not:
+
+```php
+use Tempest\Discovery\SkipDiscovery;
+use Tempest\Container\Container;
+
+#[SkipDiscovery(static function (Container $container): bool {
+    return ! $container->get(Application::class) instanceof ConsoleApplication;
+})]
+final class BlogPostEventHandlers {
+    // …
+}
+```
+
 ### Caching discovery
 
 By default, discovery is not cached, meaning all configured discovery locations are scanned on every request. This is fine for development, but in production, it's recommended to cache discovery to remove any performance overhead.

packages/database/src/QueryStatements/CreateTableStatement.php

@@ -149,8 +149,8 @@ public function text(string $name, bool $nullable = false, int|DatabaseTextLengt
         $this->statements[] = new TextStatement(
             name: $name,
             nullable: $nullable,
-            default: $default,
             length: $length,
+            default: $default,
         );
 
         return $this;

packages/discovery/src/BootDiscovery.php

@@ -5,6 +5,7 @@
 namespace Tempest\Discovery;
 
 use AssertionError;
+use Closure;
 use Pest\Exceptions\InvalidPestCommand;
 use Psr\Container\ContainerInterface;
 use Tempest\Container\GenericContainer;
@@ -214,6 +215,8 @@ private function discoverPath(string $input, DiscoveryLocation $location, array
 
                 if ($skipDiscovery !== null && $skipDiscovery->except === []) {
                     $this->shouldSkipForClass[$resolvedClassName] = true;
+                } elseif ($skipDiscovery !== null && $skipDiscovery->except instanceof Closure && ($skipDiscovery->except)($this->container)) {
+                    $this->shouldSkipForClass[$resolvedClassName] = true;
                 } elseif ($skipDiscovery !== null) {
                     foreach ($skipDiscovery->except as $except) {
                         $this->shouldSkipForClass[$resolvedClassName][$except] = true;

packages/discovery/src/SkipDiscovery.php

@@ -5,6 +5,7 @@
 namespace Tempest\Discovery;
 
 use Attribute;
+use Closure;
 
 /**
  * Instruct Tempest to not discover this class.
@@ -15,8 +16,9 @@
     public function __construct(
         /**
          * Allows the specified `Discovery` classes to still discover this class.
-         * @var array<class-string<\Tempest\Discovery\Discovery>>
+         * Pass a closure to dynamically determine if the class should be discovered.
+         * @var array<class-string<\Tempest\Discovery\Discovery>>|Closure(\Tempest\Container\Container|\Psr\Container\ContainerInterface $container): bool
          */
-        public array $except = [],
+        public Closure|array $except = [],
     ) {}
 }

packages/discovery/tests/DiscoveryTest.php

@@ -9,6 +9,8 @@
 use Tempest\Discovery\DiscoveryConfig;
 use Tempest\Discovery\DiscoveryLocation;
 use Tempest\Discovery\Tests\Fixtures\ContainerWithoutAutowiring;
+use Tempest\Discovery\Tests\Fixtures\DependencyForItemWithClosureSkip;
+use Tempest\Discovery\Tests\Fixtures\DiscoveryForItemWithClosureSkip;
 use Tempest\Discovery\Tests\Fixtures\MyDiscoveryClass;
 
 final class DiscoveryTest extends TestCase
@@ -38,6 +40,38 @@ public function test_standalone_discovery(): void
         $this->assertSame('check', MyDiscoveryClass::$discoveredItem->name);
     }
 
+    public function test_skip_discovery_with_closure(): void
+    {
+        $container = new GenericContainer();
+
+        $bootDiscovery = fn () => (new BootDiscovery(
+            container: $container,
+            config: new DiscoveryConfig(),
+        ))(
+            discoveryClasses: [
+                DiscoveryForItemWithClosureSkip::class,
+            ],
+            discoveryLocations: [
+                new DiscoveryLocation(
+                    namespace: 'Tempest\Discovery\Tests\Fixtures',
+                    path: __DIR__ . '/Fixtures',
+                ),
+            ],
+        );
+
+        // Should be skipped
+        DiscoveryForItemWithClosureSkip::$discovered = false;
+        $container->singleton(DependencyForItemWithClosureSkip::class, new DependencyForItemWithClosureSkip(true));
+        $bootDiscovery();
+        $this->assertFalse(DiscoveryForItemWithClosureSkip::$discovered);
+
+        // Should not be skipped
+        DiscoveryForItemWithClosureSkip::$discovered = false;
+        $container->singleton(DependencyForItemWithClosureSkip::class, new DependencyForItemWithClosureSkip(false));
+        $bootDiscovery();
+        $this->assertTrue(DiscoveryForItemWithClosureSkip::$discovered);
+    }
+
     public function test_discovery_with_other_container(): void
     {
         $container = new Container();

packages/discovery/tests/Fixtures/DependencyForItemWithClosureSkip.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tempest\Discovery\Tests\Fixtures;
+
+final class DependencyForItemWithClosureSkip
+{
+    public function __construct(
+        public bool $shouldSkip,
+    ) {}
+}

packages/discovery/tests/Fixtures/DiscoveryForItemWithClosureSkip.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Tempest\Discovery\Tests\Fixtures;
+
+use Tempest\Discovery\Discovery;
+use Tempest\Discovery\DiscoveryLocation;
+use Tempest\Discovery\IsDiscovery;
+use Tempest\Reflection\ClassReflector;
+
+final class DiscoveryForItemWithClosureSkip implements Discovery
+{
+    use IsDiscovery;
+
+    public static bool $discovered = false;
+
+    public function discover(DiscoveryLocation $location, ClassReflector $class): void
+    {
+        if ($class->is(ItemWithClosureSkip::class)) {
+            self::$discovered = true;
+        }
+    }
+
+    public function apply(): void
+    {
+        // TODO: Implement apply() method.
+    }
+}

packages/discovery/tests/Fixtures/ItemWithClosureSkip.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Tempest\Discovery\Tests\Fixtures;
+
+use Psr\Container\ContainerInterface;
+use Tempest\Discovery\SkipDiscovery;
+use Throwable;
+
+#[SkipDiscovery(static function (ContainerInterface $container): bool {
+    if (! $container->has(DependencyForItemWithClosureSkip::class)) {
+        return true;
+    }
+
+    try {
+        return $container->get(DependencyForItemWithClosureSkip::class)->shouldSkip;
+    } catch (Throwable) {
+        return true;
+    }
+})]
+final class ItemWithClosureSkip {}

packages/view/src/Attributes/AsAttribute.php

@@ -28,7 +28,7 @@ public function apply(Element $element): Element
 
         $generic = $element->unwrap(GenericElement::class);
 
-        if ($generic === null) {
+        if (! $generic instanceof Element) {
             return $element;
         }
 

packages/view/src/Parser/TempestViewCompiler.php

@@ -235,7 +235,7 @@ private function sourceLineMarker(int $sourceLine): string
     /** @return array{sourcePath: string|null, sourceLine: int}|null */
     private function resolveSourceLocation(Element $element): ?array
     {
-        if ($element instanceof TextElement && $element->token !== null) {
+        if ($element instanceof TextElement && $element->token instanceof Token) {
             return [
                 'sourcePath' => $element->token->sourcePath,
                 'sourceLine' => $element->token->line,