Graphql Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require avris/graphql-bundle
   

   Add to config/bundles.php:

   return [
       Avris\GraphQLBundle\AvrisGraphQLBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a GraphQL schema class with annotations:

   use Avris\GraphQLBundle\Annotation\GraphQLType;
   use Avris\GraphQLBundle\Annotation\GraphQLField;
   
   #[GraphQLType(name: 'User')]
   class UserType
   {
       #[GraphQLField]
       public function name(): string { return 'John Doe'; }
   
       #[GraphQLField]
       public function email(): string { return 'john@example.com'; }
   }
   

3. First Query Register the type in config/packages/avris_graphql.yaml:

   types:
       - Avris\GraphQLBundle\Tests\Type\UserType
   

   Run the schema generator:

   php bin/console avris:graphql:generate
   

   Test via GraphQL endpoint (/graphql by default):

   query {
       user {
           name
           email
       }
   }
   

Key First Steps

• Annotations: Focus on @GraphQLType and @GraphQLField for type/class definitions.
• Schema Generation: Run avris:graphql:generate after any schema changes.
• Debugging: Use avris:graphql:debug to inspect generated schema.

Implementation Patterns

Core Workflows

1. Type Definition

   #[GraphQLType(name: 'Product')]
   class ProductType
   {
       #[GraphQLField]
       public function id(): int { return $this->id; }
   
       #[GraphQLField(type: 'String!')] // Non-nullable string
       public function name(): string { return $this->name; }
   }
   

2. Query/Resolver Integration Bind a resolver to a query:

   #[GraphQLType(name: 'Query')]
   class QueryType
   {
       #[GraphQLField(type: 'User')]
       public function user(UserRepository $repo): UserType {
           return new UserType($repo->find(1));
       }
   }
   

3. Input Types

   #[GraphQLType(name: 'CreateUserInput')]
   class CreateUserInputType
   {
       #[GraphQLField(type: 'String!')]
       public string $name;
   
       #[GraphQLField(type: 'String!')]
       public string $email;
   }
   

4. Mutations

   #[GraphQLType(name: 'Mutation')]
   class MutationType
   {
       #[GraphQLField(type: 'User')]
       public function createUser(
           CreateUserInputType $input,
           UserService $service
       ): UserType {
           return $service->create($input);
       }
   }
   

Integration Tips

• Dependency Injection: Use constructor injection for services (e.g., UserRepository).
• Custom Scalars: Extend Avris\GraphQLBundle\Scalar\Scalar for custom types (e.g., DateTime).
• Directives: Use @GraphQLDirective for custom logic (e.g., @auth).
• Validation: Leverage PHP attributes (e.g., #[Assert\NotBlank]) for input validation.

Advanced Patterns

1. Interfaces and Unions

   #[GraphQLType(name: 'Node', isInterface: true)]
   interface NodeType {}
   
   #[GraphQLType(name: 'User', interfaces: ['Node'])]
   class UserType implements NodeType {}
   

2. Fragment Spreads

   #[GraphQLType(name: 'User', fragments: ['UserFragment'])]
   class UserType {}
   

3. Batch Loading Use Avris\GraphQLBundle\DataLoader\DataLoader for N+1 queries:

   $loader = new DataLoader($this->repository->batchFind(...));
   

Gotchas and Tips

Common Pitfalls

1. Schema Regeneration

   • Issue: Forgetting to run avris:graphql:generate after adding new types.
   • Fix: Add a post-commit hook or use php bin/console avris:graphql:watch in development.

2. Circular Dependencies

   • Issue: Types referencing each other (e.g., User → Post → User).
   • Fix: Use lazy loading or break cycles with interfaces.

3. Type Mismatches

   • Issue: Returning null for non-nullable fields (String!).
   • Fix: Use #[GraphQLField(type: 'String')] for nullable fields or ensure resolver logic handles null.

4. Annotation Caching

   • Issue: Changes to annotations not reflected until cache cleared.
   • Fix: Run php bin/console cache:clear or use avris:graphql:clear-cache.

Debugging Tips

• Schema Inspection:

  php bin/console avris:graphql:debug
  

  Outputs the full generated schema in JSON.

• Query Validation: Use GraphQL Playground (enabled by default at /graphql) to test queries interactively.

• Error Logging: Enable debug mode in config/packages/avris_graphql.yaml:

  debug: true
  

Configuration Quirks

1. Endpoint Customization Override the default /graphql endpoint in config:

   endpoint: '/api/graphql'
   

2. Middleware Add custom middleware (e.g., auth) in config/packages/avris_graphql.yaml:

   middleware:
       - Avris\GraphQLBundle\Middleware\AuthMiddleware
   

3. CORS Configure CORS in config/packages/avris_graphql.yaml:

   cors:
       allow_origin: ['*']
       allow_methods: ['GET', 'POST']
   

Extension Points

1. Custom Directives Create a directive class:

   use Avris\GraphQLBundle\Annotation\GraphQLDirective;
   
   #[GraphQLDirective(name: 'auth')]
   class AuthDirective {}
   

2. Scalar Extensions Register a custom scalar:

   scalars:
       DateTime: Avris\GraphQLBundle\Scalar\DateTimeScalar
   

3. Plugin System Implement Avris\GraphQLBundle\Plugin\PluginInterface for custom logic (e.g., logging, metrics).

4. Validation Rules Extend input validation with custom rules:

   use Avris\GraphQLBundle\Validator\Constraint;
   
   #[Constraint('Custom\Rule')]
   #[GraphQLField]
   public string $customField;