Let explicitly resolved directive classes win in classes()

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Changed
+
+- Classes passed to `DirectiveLocator::setResolved()` take precedence in `DirectiveLocator::classes()` and `DirectiveLocator::definitions()` https://github.com/nuwave/lighthouse/pull/2787
+
 ## v6.69.2
 
 ### Fixed

docs/master/custom-directives/getting-started.md

@@ -103,3 +103,25 @@ When Lighthouse encounters a directive within the schema, it starts looking for
 
 This means that our directive is already registered, just by matter of defining it in the default namespace.
 Will take precedence over potential other directives with the same name.
+
+## Override A Single Directive
+
+Namespace precedence is coarse: it applies to all directives of a namespace at once.
+To control a single directive name, bind its class explicitly in a service provider:
+
+```php
+namespace App\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Nuwave\Lighthouse\Schema\DirectiveLocator;
+use Nuwave\Lighthouse\Schema\Directives\PaginateDirective;
+
+class GraphQLServiceProvider extends ServiceProvider
+{
+    public function boot(DirectiveLocator $directiveLocator): void
+    {
+        // Use the built-in directive, even though a plugin defines its own @paginate
+        $directiveLocator->setResolved('paginate', PaginateDirective::class);
+    }
+}
+```

src/Schema/DirectiveLocator.php

@@ -33,6 +33,8 @@ class DirectiveLocator
     /**
      * A map from short directive names to full class names.
      *
+     * Takes precedence over the namespaces.
+     *
      * E.g.
      * [
      *   'create' => 'Nuwave\Lighthouse\Schema\Directives\CreateDirective',
@@ -77,8 +79,6 @@ public function namespaces(): array
      */
     public function classes(): array
     {
-        $directives = [];
-
         foreach ($this->namespaces() as $directiveNamespace) {
             /** @var array<class-string> $classesInNamespace */
             $classesInNamespace = ClassFinder::getClassesInNamespace($directiveNamespace);
@@ -94,11 +94,11 @@ public function classes(): array
                 }
 
                 // Only add the first directive that was found
-                $directives[self::directiveName($class)] ??= $class;
+                $this->resolvedClassnames[self::directiveName($class)] ??= $class;
             }
         }
 
-        return $directives;
+        return $this->resolvedClassnames;
     }
 
     /**

tests/Unit/Schema/DirectiveLocatorTest.php

@@ -6,6 +6,7 @@
 use Nuwave\Lighthouse\Exceptions\DirectiveException;
 use Nuwave\Lighthouse\Schema\DirectiveLocator;
 use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+use Nuwave\Lighthouse\Schema\Directives\ComplexityDirective;
 use Nuwave\Lighthouse\Schema\Directives\FieldDirective;
 use Nuwave\Lighthouse\Schema\Values\FieldValue;
 use Nuwave\Lighthouse\Support\Contracts\FieldMiddleware;
@@ -77,6 +78,13 @@ public function handleField(FieldValue $fieldValue): void {}
         $this->assertNotInstanceOf(BaseDirective::class, $directive);
     }
 
+    public function testResolvesExplicitlySetClassInsteadOfScannedNamespaces(): void
+    {
+        $this->directiveLocator->setResolved('field', ComplexityDirective::class);
+
+        $this->assertSame(ComplexityDirective::class, $this->directiveLocator->classes()['field']);
+    }
+
     public function testThrowsIfDirectiveNameCanNotBeResolved(): void
     {
         $this->expectException(DirectiveException::class);