Add @feature directive to conditionally add a field based on a feature state (using Laravel Pennant)

.github/workflows/validate.yml

@@ -56,6 +56,9 @@ jobs:
       - name: "Remove conflicting dependencies that are not needed here"
         run: composer remove --dev --no-update phpbench/phpbench rector/rector
 
+      - if: matrix.laravel-version != '^10'
+        run: composer remove --dev --no-update laravel/pennant
+
       - run: >
           composer require
           illuminate/contracts:${{ matrix.laravel-version }}
@@ -124,6 +127,9 @@ jobs:
       - name: "Remove conflicting dependencies that are not needed here"
         run: composer remove --dev --no-update nunomaduro/larastan phpstan/phpstan-mockery phpbench/phpbench rector/rector
 
+      - if: matrix.laravel-version != '^10'
+        run: composer remove --dev --no-update laravel/pennant
+
       - run: >
           composer require
           illuminate/contracts:${{ matrix.laravel-version }}
@@ -141,9 +147,9 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - 8.2
+          - "8.2"
         laravel-version:
-          - ^9
+          - "^10"
 
     services:
       mysql:
@@ -190,9 +196,9 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - 8.2
+          - "8.2"
         laravel-version:
-          - ^9
+          - "^10"
 
     steps:
       - uses: actions/checkout@v3

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Added
+
+- Add directive `@feature` to conditionally add annotated elements based on the state of a feature using [Laravel Pennant](https://github.com/laravel/pennant) https://github.com/nuwave/lighthouse/pull/2442 
+
 ## v6.17.0
 
 ### Added

benchmarks/QueryBench.php

@@ -13,6 +13,11 @@ abstract class QueryBench extends TestCase
     /** Cached graphQL endpoint. */
     protected string $graphQLEndpoint;
 
+    public function __construct()
+    {
+        parent::__construct(static::class);
+    }
+
     public function setUp(): void
     {
         parent::setUp();

composer.json

@@ -51,6 +51,7 @@
         "laravel/framework": "^9 || ^10",
         "laravel/legacy-factories": "^1.1.1",
         "laravel/lumen-framework": "^9 || ^10 || dev-master",
+        "laravel/pennant": "^1",
         "laravel/scout": "^8 || ^9 || ^10",
         "mattiasgeniar/phpunit-query-count-assertions": "^1.1",
         "mll-lab/graphql-php-scalars": "^6",
@@ -72,6 +73,7 @@
     },
     "suggest": {
         "bensampo/laravel-enum": "Convenient enum definitions that can easily be registered in your Schema",
+        "laravel/pennant": "Required for the @feature directive",
         "laravel/scout": "Required for the @search directive",
         "mll-lab/graphql-php-scalars": "Useful scalar types, required for @whereConditions",
         "mll-lab/laravel-graphiql": "A graphical interactive in-browser GraphQL IDE - integrated with Laravel",

docs/master/api-reference/directives.md

@@ -1074,6 +1074,49 @@ type Mutation {
 }
 ```
 
+## @feature
+
+```graphql
+"""
+Include the annotated element in the schema depending on a Laravel Pennant feature.
+"""
+directive @feature(
+    """
+    The name of the feature to be checked (can be a string or class name).
+    """
+    name: String!
+
+    """
+    Specify what the state of the feature should be for the field to be included.
+    """
+    when: FeatureState! = ACTIVE
+) on FIELD_DEFINITION | OBJECT
+
+"""
+Options for the `when` argument of `@feature`.
+"""
+enum FeatureState {
+    """
+    Indicates an active feature.
+    """
+    ACTIVE
+
+    """
+    Indicates an inactive feature.
+    """
+    INACTIVE
+}
+```
+
+Requires the installation of [Laravel Pennant](https://laravel.com/docs/pennant)
+and manual registration of the service provider in `config/app.php`:
+
+```php
+'providers' => [
+    \Nuwave\Lighthouse\Pennant\PennantServiceProvider::class,
+],
+```
+
 ## @field
 
 ```graphql

docs/master/digging-deeper/feature-toggles.md

@@ -25,9 +25,46 @@ type Query {
 }
 ```
 
+## @feature
+
+The [@feature](../api-reference/directives.md#feature) directive allows to include fields in the schema depending
+on a [Laravel Pennant](https://laravel.com/docs/pennant) feature.
+
+For example, you might want a new experimental field only to be available when the according feature is active:
+
+```graphql
+type Query {
+  experimentalField: String! @feature(name: "new-api")
+}
+```
+
+In this case, `experimentalField` will only be included when the `new-api` feature is active. 
+
+Another example would be to only include a field when the feature is inactive:
+
+```graphql
+type Query {
+  deprecatedField: String! @feature(name: "new-api", when: "INACTIVE")
+}
+```
+
+When using [class based features](https://laravel.com/docs/pennant#class-based-features), 
+the fully qualified class name must be used as the value for the `name` argument:
+
+```graphql
+type Query {
+  experimentalField: String! @feature(name: "App\\Features\\NewApi")
+}
+```
+
 ## Interaction With Schema Cache
 
 [@show](../api-reference/directives.md#show) and [@hide](../api-reference/directives.md#hide) work by manipulating the schema.
 This means that when using their `env` option, the inclusion or exclusion of elements depends on the value
 of `app()->environment()` at the time the schema is built and not update on later environment changes.
 If you are pre-generating your schema cache, make sure to match the environment to your deployment target.
+
+The same goes for [@feature](../api-reference/directives.md#feature). Whether a field is included in the schema will be
+based on the state of a feature at the time the schema is built. In addition, if you are pre-generating your schema cache, 
+you will only be able to use features that support [nullable scopes](https://laravel.com/docs/pennant#nullable-scope), 
+as there won't be an authenticated user to check the feature against.

phpstan.neon

@@ -15,6 +15,9 @@ parameters:
   excludePaths:
   - tests/Utils/Models/WithoutRelationClassImport.php # Intentionally wrong
   - tests/LaravelPhpdocAlignmentFixer.php # Copied from laravel/pint
+  # laravel/pennant requires Laravel 10
+  - src/Pennant
+  - tests/Integration/Pennant
   ignoreErrors:
   # PHPStan does not get it
   - '#Parameter \#1 \$callback of static method Closure::fromCallable\(\) expects callable\(\): mixed, array{object, .*} given\.#'
@@ -24,6 +27,7 @@ parameters:
   - path: tests/database/factories/*
     message: '#Variable \$factory might not be defined#'
 
+
   # Mixins are magical
   - path: src/Testing/TestResponseMixin.php
     message: '#Method Nuwave\\Lighthouse\\Testing\\TestResponseMixin::assertGraphQLErrorMessage\(\) invoked with 1 parameter, 0 required\.#'

src/Pennant/FeatureDirective.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types=1);
+
+namespace Nuwave\Lighthouse\Pennant;
+
+use Laravel\Pennant\FeatureManager;
+use Nuwave\Lighthouse\Exceptions\DefinitionException;
+use Nuwave\Lighthouse\Schema\Directives\HideDirective;
+
+final class FeatureDirective extends HideDirective
+{
+    public function __construct(
+        private FeatureManager $features,
+    ) {
+        parent::__construct();
+    }
+
+    public static function definition(): string
+    {
+        return /** @lang GraphQL */ <<<'GRAPHQL'
+"""
+Include the annotated element in the schema depending on a Laravel Pennant feature.
+"""
+directive @feature(
+    """
+    The name of the feature to be checked (can be a string or class name).
+    """
+    name: String!
+
+    """
+    Specify what the state of the feature should be for the field to be included.
+    """
+    when: FeatureState! = ACTIVE
+) on FIELD_DEFINITION | OBJECT
+
+"""
+Options for the `when` argument of `@feature`.
+"""
+enum FeatureState {
+    """
+    Indicates an active feature.
+    """
+    ACTIVE
+
+    """
+    Indicates an inactive feature.
+    """
+    INACTIVE
+}
+GRAPHQL;
+    }
+
+    protected function shouldHide(): bool
+    {
+        $feature = $this->directiveArgValue('name');
+        $requiredFeatureState = $this->directiveArgValue('when', 'ACTIVE');
+
+        return match ($requiredFeatureState) {
+            'ACTIVE' => $this->features->inactive($feature),
+            'INACTIVE' => $this->features->active($feature),
+            default => throw new DefinitionException("Expected FeatureState `ACTIVE` or `INACTIVE` for argument `when` of @{$this->name()} on {$this->nodeName()}, got `{$requiredFeatureState}`."),
+        };
+    }
+}

src/Pennant/PennantServiceProvider.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types=1);
+
+namespace Nuwave\Lighthouse\Pennant;
+
+use Illuminate\Contracts\Events\Dispatcher;
+use Illuminate\Support\ServiceProvider;
+use Nuwave\Lighthouse\Events\RegisterDirectiveNamespaces;
+
+final class PennantServiceProvider extends ServiceProvider
+{
+    public function boot(Dispatcher $dispatcher): void
+    {
+        $dispatcher->listen(RegisterDirectiveNamespaces::class, static fn (): string => __NAMESPACE__);
+    }
+}