GraphQL Fragments in Twig Templates

GraphQL Fragments in Twig Templates

  Traditional GraphQL queries often become "monster queries" - massive operations where you're
afraid to remove any field because it might be used somewhere deep in your template hierarchy. You
end up with bloated queries that fetch unnecessary
  data, making maintenance a nightmare.

  This new feature solves that problem by letting you co-locate data requirements with your
templates. Each Twig template can define exactly what GraphQL data it needs through fragments,
ensuring perfect alignment between your views and their data
  dependencies.

  How it works

  Controller: Keep queries simple - just reference the top-level fragment
  final readonly class SomeController
  {
      private const string OPERATION = <<<'GRAPHQL'
          query Projects {
              ...AdminProjectList
          }
          GRAPHQL;

      public function __invoke(): string
      {
          return $this->twig->render('list.html.twig', [
              'data' => $this->query->executeOrThrow()->adminProjectList,
          ]);
      }
  }

  Main template (list.html.twig): Define what data this template needs
  {% graphql %}
  fragment AdminProjectList on Query {
      viewer { name }
      projects {
          ...AdminProjectRow
      }
  }
  {% endgraphql %}

  <h1>Good day, {{ data.viewer.name }}</h1>
GraphQL Fragments in Twig Templates

Traditional GraphQL queries often become "monster queries" - massive operations where you're afraid
to remove any field because it might be used somewhere deep in your template hierarchy. You end up
with bloated queries that fetch unnecessary
data, making maintenance a nightmare.

This new feature solves that problem by letting you co-locate data requirements with your templates.
Each Twig template can define exactly what GraphQL data it needs through fragments, ensuring perfect
alignment between your views and their data
dependencies.

## How it works

Controller: Keep queries simple - just reference the top-level fragment
```php
final readonly class SomeController
{
    private const string OPERATION = <<<'GRAPHQL'
        query Projects {
            ...AdminProjectList
        }
        GRAPHQL;

    public function __invoke(): string
    {
        return $this->twig->render('list.html.twig', [
            'data' => $this->query->executeOrThrow()->adminProjectList,
        ]);
    }
}
```

Main template (list.html.twig): Define what data this template needs

```twig
{% graphql %}
fragment AdminProjectList on Query {
    viewer { name }
    projects {
        ...AdminProjectRow
    }
}
{% endgraphql %}

<h1>Good day, {{ data.viewer.name }}</h1>
{% for project in data.projects %}
    {{ include('_project_row.html.twig', {project: project.adminProjectRow}) }}
{% endfor %}
```

Partial template (_project_row.html.twig): Each partial declares its own requirements

```twig
{% graphql %}
fragment AdminProjectRow on Project {
    id
    name
    description
    ...AdminProjectOptions
}
{% endgraphql %}

<li>#{{ project.id }} - {{ project.name }}</li>
```

## Setup

Enable Twig processing:
```php
$config->withTwigProcessingDirectory(__DIR__ . '/templates')
```

For Twig CS Fixer:
```php
$config->addTokenParser(new GraphQLTokenParser());
```

For Symfony:
```php
$services->set(\Ruudk\GraphQLCodeGenerator\Twig\GraphQLExtension::class)->tag('twig.extension');
```

Each template owns its data requirements, making refactoring safe and predictable. No more guessing
which fields are actually used - the data dependencies are right there with the template that needs
them.

Author: ruudk

.github/workflows/ci.yml

@@ -50,6 +50,9 @@ jobs:
       - name: Run PHP CS Fixer
         run: vendor/bin/php-cs-fixer check --diff
 
+      - name: Run Twig CS Fixer
+        run: vendor/bin/twig-cs-fixer lint
+
       - name: Run PHPStan
         run: vendor/bin/phpstan analyse
 

.gitignore

@@ -3,3 +3,4 @@
 /vendor/
 /.php-cs-fixer.cache
 /.phpunit.cache/
+/.twig-cs-fixer.cache

.twig-cs-fixer.php

@@ -0,0 +1,24 @@
+<?php
+
+use Ruudk\GraphQLCodeGenerator\Twig\GraphQLTokenParser;
+use TwigCsFixer\Ruleset\Ruleset;
+use TwigCsFixer\Standard\TwigCsFixer;
+use TwigCsFixer\File\Finder;
+use TwigCsFixer\Config\Config;
+
+$ruleset = new Ruleset();
+
+$ruleset->addStandard(new TwigCsFixer());
+
+$finder = Finder::create()
+    ->in('tests');
+
+$config = new Config();
+$config->allowNonFixableRules();
+$config->setCacheFile(__DIR__ . '/.twig-cs-fixer.cache');
+$config->setRuleset($ruleset);
+$config->setFinder($finder);
+$config->addTokenParser(new GraphQLTokenParser());
+
+return $config;
+

captainhook.json

@@ -22,7 +22,10 @@
                 "action": "\\CaptainHook\\App\\Hook\\PHP\\Action\\Linting"
             },
             {
-                "action": "vendor/bin/php-cs-fixer check --diff"
+                "action": "vendor/bin/php-cs-fixer fix"
+            },
+            {
+                "action": "vendor/bin/twig-cs-fixer fix"
             },
             {
                 "action": "vendor/bin/phpstan"

composer-dependency-analyser.php

@@ -3,9 +3,12 @@
 declare(strict_types=1);
 
 use ShipMonk\ComposerDependencyAnalyser\Config\Configuration;
+use ShipMonk\ComposerDependencyAnalyser\Config\ErrorType;
 
 $config = new Configuration();
 
 $config->addPathToScan(__DIR__ . '/bin', isDev: false);
 
+$config->ignoreErrorsOnPackage('twig/twig', [ErrorType::DEV_DEPENDENCY_IN_PROD]);
+
 return $config;

composer.json

@@ -5,6 +5,7 @@
     "type": "library",
     "require": {
         "php": "^8.4",
+        "composer-runtime-api": "^2.0",
         "nikic/php-parser": "^5.6",
         "phpstan/phpstan": "^2.1",
         "ruudk/code-generator": "^0.4.3",
@@ -40,7 +41,12 @@
         "symfony/dotenv": "^7.3",
         "symfony/var-dumper": "^7.3",
         "ticketswap/php-cs-fixer-config": "^1.0",
-        "ticketswap/phpstan-error-formatter": "^1.1"
+        "ticketswap/phpstan-error-formatter": "^1.1",
+        "twig/twig": "^3.21",
+        "vincentlanglet/twig-cs-fixer": "^3.9"
+    },
+    "suggest": {
+        "twig/twig": "For generating GraphQL fragments from Twig templates"
     },
     "autoload": {
         "psr-4": {

composer.lock

@@ -21,6 +21,7 @@
      * @param list<TypeInitializer\TypeInitializer> $typeInitializers
      * @param null|object|(Closure(): object) $introspectionClient
      * @param list<string> $inlineProcessingDirectories
+     * @param list<string> $twigProcessingDirectories
      */
     private function __construct(
         public Schema | string $schema,
@@ -48,6 +49,7 @@ private function __construct(
         public bool $dumpEnumIsMethods = false,
         public ?object $introspectionClient = null,
         public array $inlineProcessingDirectories = [],
+        public array $twigProcessingDirectories = [],
         public bool $formatOperationFiles = false,
     ) {}
 
@@ -187,6 +189,11 @@ public function withInlineProcessingDirectory(string $directory, string ...$dire
         return $this->with('inlineProcessingDirectories', [...$this->inlineProcessingDirectories, $directory, ...$directories]);
     }
 
+    public function withTwigProcessingDirectory(string $directory, string ...$directories) : self
+    {
+        return $this->with('twigProcessingDirectories', [...$this->twigProcessingDirectories, $directory, ...$directories]);
+    }
+
     /**
      * Replace with clone with when in PHP 8.5
      */

src/Config/Config.php

@@ -4,9 +4,11 @@
 
 namespace Ruudk\GraphQLCodeGenerator;
 
+use Composer\InstalledVersions;
 use Exception;
 use GraphQL\Error\InvariantViolation;
 use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Language\AST\FragmentDefinitionNode;
 use GraphQL\Language\AST\NodeList;
 use GraphQL\Language\AST\OperationDefinitionNode;
 use GraphQL\Language\Parser;
@@ -76,6 +78,8 @@
 use Ruudk\GraphQLCodeGenerator\Planner\SelectionSetPlanner;
 use Ruudk\GraphQLCodeGenerator\Planner\Source\FileSource;
 use Ruudk\GraphQLCodeGenerator\Planner\Source\InlineSource;
+use Ruudk\GraphQLCodeGenerator\Twig\GraphQLExtension;
+use Ruudk\GraphQLCodeGenerator\Twig\GraphQLNodeFinder;
 use Ruudk\GraphQLCodeGenerator\Type\TypeHelper;
 use Ruudk\GraphQLCodeGenerator\Validator\IndexByValidator;
 use Ruudk\GraphQLCodeGenerator\Visitor\DefinedFragmentsVisitor;
@@ -89,6 +93,8 @@
 use Symfony\Component\TypeInfo\Type as SymfonyType;
 use Symfony\Component\TypeInfo\Type\BackedEnumType;
 use Symfony\Component\TypeInfo\TypeIdentifier;
+use Twig\Environment;
+use Twig\Loader\ArrayLoader;
 use Webmozart\Assert\Assert;
 use Webmozart\Assert\InvalidArgumentException;
 
@@ -287,6 +293,8 @@ public function plan() : PlannerResult
 
                             Assert::notNull($definition->name, 'Expected operation to have a name');
 
+                            $usedTypesCollector->analyze($document);
+
                             $operationType = $definition->operation;
                             $operationName = $definition->name->value;
 
@@ -312,6 +320,36 @@ public function plan() : PlannerResult
             }
         }
 
+        if ($this->config->twigProcessingDirectories !== []) {
+            Assert::true(InstalledVersions::isInstalled('twig/twig'), 'Twig is required to use twigProcessingDirectories');
+
+            $twig = new Environment(new ArrayLoader([]));
+            $twig->addExtension(new GraphQLExtension());
+            $nodeFinder = new GraphQLNodeFinder($twig);
+
+            $finder = Finder::create()
+                ->files()
+                ->in($this->config->inlineProcessingDirectories)
+                ->name('*.twig')
+                ->contains('{% graphql %}');
+
+            foreach ($finder as $file) {
+                foreach ($nodeFinder->find($file->getContents()) as $operation) {
+                    $document = Parser::parse($operation);
+
+                    Assert::minCount($document->definitions, 1);
+                    Assert::allIsInstanceOf($document->definitions, FragmentDefinitionNode::class, 'Only fragment definitions are supported in Twig templates');
+
+                    $usedTypesCollector->analyze($document);
+
+                    $operations[$file->getPathname()][] = DocumentNodeWithSource::create(
+                        $document,
+                        new FileSource(Path::makeRelative($file->getPathname(), $this->config->projectDir)),
+                    );
+                }
+            }
+        }
+
         $usedTypes = $usedTypesCollector->usedTypes;
 
         // Initialize enum and input types based on usage

src/Planner.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ruudk\GraphQLCodeGenerator\Twig;
+
+use Override;
+use Twig\Extension\AbstractExtension;
+
+final class GraphQLExtension extends AbstractExtension
+{
+    #[Override]
+    public function getTokenParsers() : array
+    {
+        return [
+            new GraphQLTokenParser(),
+        ];
+    }
+}