Getting Started

Minimal Setup

Installation:
```
composer require google/cloud-error-reporting
```
Ensure your Laravel project has the google/cloud-core and google/auth packages as dependencies (they are auto-installed via google/cloud-error-reporting).
Authentication: Configure Google Cloud credentials via:
- Environment variable (GOOGLE_APPLICATION_CREDENTIALS pointing to a service account JSON key file).
- Laravel's .env:
```
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

First Use Case: Report a critical exception in a Laravel controller:

use Google\Cloud\ErrorReporting\V1beta1\ErrorReportingServiceClient;
use Google\Cloud\ErrorReporting\V1beta1\ReportedErrorEvent;

try {
    // Your business logic
} catch (\Exception $e) {
    $client = new ErrorReportingServiceClient();
    $event = (new ReportedErrorEvent())
        ->setMessage($e->getMessage())
        ->setServiceContext((new \Google\Cloud\ErrorReporting\V1beta1\ServiceContext())
            ->setService($this->app->environment())
            ->setVersion('1.0.0'));

    $client->reportErrorEvent($event);
    throw $e; // Re-throw to maintain Laravel's exception handling
}

Key Classes to Know

ErrorReportingServiceClient: Main client for reporting errors.
ReportedErrorEvent: Represents an error event to report.
ErrorGroupServiceClient: For querying existing error groups (e.g., for debugging).

Implementation Patterns

1. Exception Handling Integration

Workflow:

Use Laravel's App\Exceptions\Handler to catch exceptions and report them to Stackdriver.

Example:

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Google\Cloud\ErrorReporting\V1beta1\ReportedErrorEvent;

class Handler extends ExceptionHandler
{
    public function report(\Throwable $exception)
    {
        parent::report($exception);

        $client = new ErrorReportingServiceClient();
        $event = (new ReportedErrorEvent())
            ->setMessage($exception->getMessage())
            ->setServiceContext((new \Google\Cloud\ErrorReporting\V1beta1\ServiceContext())
                ->setService(app()->environment())
                ->setVersion(config('app.version', '1.0.0')))
            ->setContext((new \Google\Cloud\ErrorReporting\V1beta1\ErrorContext())
                ->setUser((new \Google\Cloud\ErrorReporting\V1beta1\UserInfo())
                    ->setEmail(auth()->user()?->email ?? 'anonymous'))
                ->setHttpRequest((new \Google\Cloud\ErrorReporting\V1beta1\HttpRequest())
                    ->setUrl(request()->fullUrl())
                    ->setMethod(request()->method())));

        $client->reportErrorEvent($event);
    }
}

2. Context Enrichment

Add contextual data to errors for better debugging:

$event = (new ReportedErrorEvent())
    ->setMessage($e->getMessage())
    ->setServiceContext((new \Google\Cloud\ErrorReporting\V1beta1\ServiceContext())
        ->setService('laravel-app')
        ->setVersion('1.0.0'))
    ->setContext((new \Google\Cloud\ErrorReporting\V1beta1\ErrorContext())
        ->setUser((new \Google\Cloud\ErrorReporting\V1beta1\UserInfo())
            ->setEmail(auth()->user()?->email))
        ->setHttpRequest((new \Google\Cloud\ErrorReporting\V1beta1\HttpRequest())
            ->setUrl(request()->fullUrl())
            ->setMethod(request()->method())
            ->setReferrer(request()->header('referer')))
        ->setLabels([
            'user_id' => auth()->id(),
            'request_id' => request()->header('X-Request-ID'),
        ]));

3. Querying Error Groups

Fetch error groups for debugging:

$errorGroupClient = new ErrorGroupServiceClient();
$request = (new \Google\Cloud\ErrorReporting\V1beta1\ListGroupsRequest())
    ->setFilter('service="laravel-app"')
    ->setPageSize(10);

$iterator = $errorGroupClient->listGroups($request);
foreach ($iterator as $group) {
    Log::debug('Error Group ID: ' . $group->getGroupId());
}

4. Logging Integration

Combine with Laravel's logging for unified observability:

// In AppServiceProvider's boot method
public function boot()
{
    \Log::listen(function ($level, $context, $timestamp) {
        if ($level === 'error' && $context['exception']) {
            $client = new ErrorReportingServiceClient();
            $event = (new ReportedErrorEvent())
                ->setMessage($context['message'])
                ->setServiceContext((new \Google\Cloud\ErrorReporting\V1beta1\ServiceContext())
                    ->setService(app()->environment()))
                ->setContext((new \Google\Cloud\ErrorReporting\V1beta1\ErrorContext())
                    ->setUser((new \Google\Cloud\ErrorReporting\V1beta1\UserInfo())
                        ->setEmail(auth()->user()?->email)));

            $client->reportErrorEvent($event);
        }
    });
}

5. Environment-Specific Reporting

Disable reporting in local environments:

if (!app()->isLocal()) {
    $client->reportErrorEvent($event);
}

Gotchas and Tips

Pitfalls

Authentication Issues:
- Ensure GOOGLE_APPLICATION_CREDENTIALS is set or the service account JSON is properly configured.
- Avoid hardcoding credentials in your codebase. Use Laravel's .env or environment variables.
- Tip: Use google/cloud-core's CredentialsFactory for dynamic credential loading:
```
use Google\Auth\Credentials\CredentialsFactory;
$credentials = CredentialsFactory::serviceAccountFromKeyFile(
    env('GOOGLE_APPLICATION_CREDENTIALS')
);
$client = new ErrorReportingServiceClient(['credentials' => $credentials]);
```
Rate Limiting:
- Stackdriver Error Reporting has quotas (e.g., 100,000 error events per day). Monitor usage in the Google Cloud Console.
- Tip: Batch errors if reporting high-volume events (e.g., during migrations).
Deprecated Methods:
- The package removed deprecated GAPICs in v0.26.0. Ensure you’re using the latest methods (e.g., reportErrorEvent instead of older variants).
- Tip: Check the changelog for breaking changes.
Context Size Limits:
- Error context (e.g., labels, HTTP requests) is limited to 100KB. Avoid attaching large payloads.
- Tip: Sanitize or truncate sensitive data (e.g., passwords) before reporting:
```
$context->setLabels(array_filter($labels, fn($value) => strlen($value) < 100, ARRAY_FILTER_USE_VALUE));
```
PHP 8.4 Compatibility:
- The package supports PHP 8.4, but some older Laravel versions (e.g., < 9.x) may have compatibility issues.
- Tip: Test in a staging environment before upgrading.

Debugging Tips

Enable Debug Logging: Configure the client to log HTTP requests/responses:

$client = new ErrorReportingServiceClient([
    'logger' => new \Google\ApiCore\Logging\Logger(
        new \Monolog\Logger('grpc', [new \Monolog\Handler\StreamHandler('php://stderr')])
    ),
]);

Validate Error Groups: Use the getGroup method to verify if an error was reported:

$groupName = 'projects/YOUR_PROJECT/locations/global/errorGroups/GROUP_ID';
$response = $errorGroupClient->getGroup((new \Google\Cloud\ErrorReporting\V1beta1\GetGroupRequest())
    ->setGroupName($groupName));

Check for Throttling: If requests fail with 429 Too Many Requests, implement exponential backoff:

use Google\ApiCore\Retry\RetrySettings;
$client = new ErrorReportingServiceClient([
    'retrySettings' => new RetrySettings(['maxAttempts' => 3, 'backoffFactor' => 1.5]),
]);

Extension Points

Custom Error Transformers: Create a transformer to standardize error reporting across your app:

class ErrorTransformer
{
    public static function transform(\Throwable $exception): ReportedErrorEvent
    {
        return (new ReportedErrorEvent())
            ->setMessage($exception->get

Cloud Error Reporting Laravel Package