Google Cloud Error Reporting Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require crassula/google-cloud-error-reporting-bundle
   

   Ensure your composer.json includes the PECL extensions (grpc, protobuf) for optimal performance.

2. Register the Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Crassula\Bundle\GoogleCloudErrorReportingBundle\CrassulaGoogleCloudErrorReportingBundle::class => ['all' => true],
   ];
   

3. Configure in config/packages/crassula_google_cloud_error_reporting.yaml

   crassula_google_cloud_error_reporting:
       enabled: true
       project_id: "your-gcp-project-id"
       service: "your-service-name"
       client_options:
           credentials: "%kernel.project_dir%/config/gcp_credentials.json"
   

4. First Use Case: Manual Error Reporting Inject ErrorReporter and report exceptions explicitly:

   use Crassula\Bundle\GoogleCloudErrorReportingBundle\Service\ErrorReporter;
   
   try {
       $this->riskyOperation();
   } catch (\Exception $e) {
       $this->errorReporter->report($e, [
           'http_request' => $request,
           'user' => $user->getEmail(),
       ]);
   }
   

Implementation Patterns

Core Workflows

1. Automatic Error Reporting (Recommended) Enable use_listeners: true in config to auto-capture:

   • kernel.exception (web)
   • console.error (CLI) Reports trigger on kernel.terminate/console.terminate.

2. Conditional Reporting Use ignore_exceptions to exclude specific exceptions (e.g., ValidationFailedHttpException):

   crassula_google_cloud_error_reporting:
       ignore_exceptions:
           - Symfony\Component\HttpKernel\Exception\ValidationException
   

3. Contextual Data Attach metadata to errors via the second argument:

   $this->errorReporter->report($e, [
       'http_response_status_code' => 500,
       'user' => $user->getId(),
       'request_options' => [
           'retrySettings' => new \Google\ApiCore\RetrySettings(['maxAttempts' => 3]),
       ],
   ]);
   

4. Symfony Monolog Integration Log failed reports to Monolog (default behavior) by configuring the logger option:

   crassula_google_cloud_error_reporting:
       logger: "monolog.logger.error_reporting"
   

Integration Tips

• Environment-Specific Configs Disable in config/packages/dev/crassula_google_cloud_error_reporting.yaml:

  crassula_google_cloud_error_reporting:
      enabled: false
  

• Dependency Injection Tag ErrorReporter as a service for autowiring:

  services:
      Crassula\Bundle\GoogleCloudErrorReportingBundle\Service\ErrorReporter:
          tags: ['container.service_subscriber']
  

• Custom Error Groups Use the service_version config to segment errors by deployment:

  crassula_google_cloud_error_reporting:
      service_version: "1.2.3"
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Symptom: Errors silently fail if credentials are invalid or missing.
   • Fix: Validate credentials locally:

     php -r "require 'vendor/autoload.php'; $client = new \Google\Cloud\ErrorReporting\ErrorReportingClient(['credentials' => 'path/to/key.json']);"
     

   • Debug: Enable logger to log auth errors:

     crassula_google_cloud_error_reporting:
         logger: "monolog.logger.error_reporting"
     

2. Performance Overhead

   • Symptom: High latency in production due to gRPC calls.
   • Fix: Disable auto-reporting for non-critical paths and use manual reporting:

     crassula_google_cloud_error_reporting:
         use_listeners: false
     

3. Duplicate Reports

   • Cause: Listeners trigger multiple times for the same exception (e.g., in middleware).
   • Fix: Use ignore_exceptions or implement a ReportedException decorator:

     // src/Service/ReportedException.php
     class ReportedException extends \Exception {}
     

4. PHP 7.4+ Requirement

   • Issue: Older PHP versions throw TypeError on native type hints.
   • Workaround: Downgrade to v0.7.0 (pre-7.4) if needed.

Debugging Tips

• Check Reported Errors Use the Google Cloud Console to verify errors appear. Filter by service and service_version in config.

• Local Testing Mock the ErrorReporter in tests:

  $this->container->set(ErrorReporter::class, $this->createMock(ErrorReporter::class));
  

• Config Validation Run:

  bin/console debug:config crassula_google_cloud_error_reporting
  

  To validate your configuration.

Extension Points

1. Custom Error Reporter Implement Crassula\Bundle\GoogleCloudErrorReportingBundle\Service\ErrorReporterInterface:

   class CustomErrorReporter implements ErrorReporterInterface {
       public function report(\Throwable $exception, array $options = []): void {
           // Custom logic (e.g., Slack alerts)
       }
   }
   

   Register as a service and override the bundle’s default.

2. Event Subscribers Extend the kernel.exception event to enrich data:

   use Symfony\Component\HttpKernel\Event\ExceptionEvent;
   
   $subscriber = new class {
       public function onKernelException(ExceptionEvent $event) {
           $exception = $event->getThrowable();
           $event->getRequest()->attributes->set('gcp_error_group', 'api-failure');
       }
   };
   

3. Retry Logic Configure retry settings in client_options:

   crassula_google_cloud_error_reporting:
       client_options:
           retrySettings:
               maxAttempts: 5
               initialDelay: 100ms