Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require ciloe/graphql-client-bundle

Enable the bundle in config/bundles.php:

return [
    // ...
    Ciloe\GraphQLClientBundle\CiloeGraphQLClientBundle::class => ['all' => true],
];

Basic Configuration Configure the client in config/packages/ciloe_graphql_client.yaml:

ciloe_graphql_client:
    endpoint: 'https://your-graphql-endpoint.com/graphql'
    headers:
        Authorization: 'Bearer YOUR_TOKEN'

First Query Inject the client service and execute a query:

use Ciloe\GraphQLClientBundle\Service\GraphQLClient;

class MyController extends AbstractController
{
    public function __construct(private GraphQLClient $client)
    {
    }

    public function queryExample()
    {
        $query = '
            query {
                user(id: 1) {
                    name
                    email
                }
            }
        ';
        $result = $this->client->query($query);
        return $this->json($result);
    }
}

Where to Look First

Bundle Usage Docs – Core usage patterns.
Query Service Docs – Customizing query execution.
Configuration Guide – Adjusting endpoints, headers, and caching.

Implementation Patterns

Query Execution Workflows

Direct Query Execution Use the query() method for one-off requests:
```
$result = $client->query($queryString);
```
Named Queries (Recommended for Reusability) Define queries in YAML/JSON files (e.g., config/graphql/queries/user.yaml):
```
user:
    query: 'query { user(id: $id) { name } }'
    variables: { id: 1 }
```
Load and execute via the service:
```
$result = $client->queryFromFile('user', ['id' => 1]);
```

Variable Binding Pass variables dynamically:

$query = 'query GetUser($id: ID!) { user(id: $id) { name } }';
$result = $client->query($query, ['id' => 2]);

Mutation Support Use the mutate() method for mutations:

$mutation = '
    mutation CreateUser($input: UserInput!) {
        createUser(input: $input) { id }
    }
';
$result = $client->mutate($mutation, ['input' => ['name' => 'John']]);

Integration with Symfony Ecosystem

Dependency Injection Inject GraphQLClient into controllers, services, or commands:
```
public function __construct(private GraphQLClient $client) {}
```

Event Listeners/Subscribers Extend functionality by listening to graphql.client.query events:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Ciloe\GraphQLClientBundle\Event\QueryEvent;

class GraphQLLoggerSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [QueryEvent::NAME => 'onQuery'];
    }

    public function onQuery(QueryEvent $event)
    {
        // Log or modify the query/variables
    }
}

Caching Strategies Leverage the built-in cache service:

# config/packages/ciloe_graphql_client.yaml
ciloe_graphql_client:
    cache:
        enabled: true
        provider: 'cache.app' # Symfony cache service ID

Cache queries automatically by normalizing variables:

$client->query($query, ['id' => 1]); // Cached with key: "query_hash:id:1"

Error Handling Wrap queries in try-catch blocks:

try {
    $result = $client->query($query);
} catch (GraphQLClientException $e) {
    // Handle errors (e.g., network issues, GraphQL errors)
    $this->addFlash('error', $e->getMessage());
}

Gotchas and Tips

Common Pitfalls

Deprecated Package
- Last updated in 2018—expect missing features (e.g., no support for GraphQL subscriptions, limited error handling).
- Mitigation: Extend the bundle or use a modern alternative like webonyx/graphql-php.
Cache Key Collisions
- The cache normalizes variables, but complex objects (e.g., DateTime) may cause issues.
- Fix: Implement a custom cache key generator in the service:
```
$client->setCacheKeyGenerator(function ($query, $variables) {
    return md5($query . json_encode($variables, JSON_UNESCAPED_UNICODE));
});
```
Header Injection Risks
- Hardcoded headers in config may expose tokens.
- Tip: Use Symfony’s %env% or parameter bags:
```
headers:
    Authorization: '%env(API_TOKEN)%'
```

No Built-in Retry Logic

Network failures will throw exceptions immediately.

Workaround: Wrap calls in a retry service:

use Symfony\Component\Retry\Retry;

$retry = new Retry(3, 100); // 3 retries, 100ms delay
$result = $retry->retry(function () use ($client, $query) {
    return $client->query($query);
});

Debugging Tips

Enable Verbose Logging Add to config/packages/monolog.yaml:

handlers:
    graphql:
        type: stream
        path: '%kernel.logs_dir%/graphql.log'
        level: debug
        channels: ['graphql']

Then enable the channel in the bundle config:

ciloe_graphql_client:
    logging:
        enabled: true
        channel: 'graphql'

Inspect Raw Responses Use the rawQuery() method to bypass processing:

$response = $client->rawQuery($query);
// Dump the full HTTP response
file_put_contents('debug.graphql', print_r($response, true));

Variable Validation The bundle doesn’t validate variables against the schema. Use a tool like GraphQL Playground or Altair to test queries first.

Extension Points

Custom HTTP Client Override the default GuzzleHttp\Client by binding a new service:

# config/services.yaml
services:
    Ciloe\GraphQLClientBundle\Service\GraphQLClient:
        arguments:
            $httpClient: '@your_custom.http_client'

Query Preprocessing Add middleware to modify queries/variables before execution:

$client->addMiddleware(function ($query, $variables) {
    // Add auth headers dynamically
    $variables['authToken'] = $this->getAuthToken();
    return [$query, $variables];
});

Response Transformation Extend the response parser to normalize data:

$client->setResponseParser(function ($response) {
    $data = json_decode($response->getBody(), true);
    return $this->transformResponse($data);
});

Schema Introspection The bundle lacks introspection tools. Use a separate library like graphql-php for schema-aware development.

Graphql Client Bundle Laravel Package