bright-alley/lighthouse-apollo

Integration to upload information from Laravel Lighthouse to Apollo Studio.

v3.0 2023-08-04 11:52 UTC

README

This library allows integrating your Lighthouse GraphQL project with Apollo Studio, sending tracing statistics and allowing you to send your schema to Apollo for breaking changes notifications.

Lighthouse requirements

This library is tested with Lighthouse 6.

For Lighthouse 4.x, use version 1.x of this library. For Lighthouse 5.x, use version 2.x of this library.

Installation

First, install the Composer package:

composer require bright-alley/lighthouse-apollo

Next, publish the config file and adjust it as desired:

php artisan vendor:publish --provider="BrightAlley\LighthouseApollo\ServiceProvider"

The service provider for this package is automatically registered. If you have disabled auto-discovery of service providers, make sure to add \BrightAlley\LighthouseApollo\ServiceProvider to your service providers. Lighthouse's TracingServiceProvider is automatically registered. By default, the tracing results are stripped from the actual GraphQL response when not in debug mode.

When using the redis or database send tracing mode (highly recommended for production usage), make sure to add the lighthouse-apollo:publish-tracing artisan command to your console kernel's schedule, so it runs frequently to send queued trace results to Apollo. You can adjust the schedule to run more or less often based on your traffic volume.

public function schedule(\Illuminate\Console\Scheduling\Schedule $schedule)
{
    $schedule->command('lighthouse-apollo:submit-tracing')
        ->everyMinute();
}

Client tracing

You can gather information about which clients are calling your GraphQL API. If you have control over the clients, add the x-apollo-client-name and x-apollo-client-version headers to your GraphQL requests, and they will be gathered and sent to Apollo Studio.

If you need more control over client tracing on the server side, you can create your own custom logic by implementing the BrightAlley\LighthouseApollo\Contracts\ClientInformationExtractor interface, and binding your own implementation to the app container in your service provider, like so:

$this->app->bind(ClientInformationExtractor::class, MyCustomClientInformationExtractor::class);

Development

Protobuf is used for sending traces to Apollo Studio. To generate new stubs, use the following command:

protoc -I resources --php_out=generated/ resources/*.proto