Laravel Error Share Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-error-share
   

   Publish the config file (optional, but recommended for customization):

   php artisan vendor:publish --provider="Spatie\ErrorShare\ErrorShareServiceProvider"
   

2. First Use Case: Trigger an error in your Laravel app (e.g., 1/0 in a route or controller) and visit the generated error share URL. The package automatically generates a unique shareable link (e.g., http://your-app.test/share/errors/abc123) for each error.

3. Where to Look First:

   • Config File: config/error-share.php (for customization like base URL, expiration, or Flare integration).
   • Middleware: Spatie\ErrorShare\ShareErrorMiddleware (handles error sharing logic).
   • Artisan Command: php artisan error-share:share (manual sharing for non-HTTP errors).

Implementation Patterns

Core Workflows

1. Automatic Sharing:

   • Register the middleware in app/Http/Kernel.php under $middleware (for global sharing) or $routeMiddleware (for specific routes):

     'share-error' => \Spatie\ErrorShare\ShareErrorMiddleware::class,
     

   • Use it in routes:

     Route::get('/debug', function () {
         throw new \Exception('Test error');
     })->middleware('share-error');
     

2. Manual Sharing:

   • For non-HTTP errors (e.g., CLI, queues), use the Artisan command:

     php artisan error-share:share --error="[object] (Exception(code: 0): Test error at ...)"
     

   • Or programmatically:

     use Spatie\ErrorShare\ErrorShare;
     
     ErrorShare::share(new \Exception('Manual error'));
     

3. Flare Integration:

   • Configure flare_api_key in config/error-share.php to auto-upload errors to Laravel Flare.
   • Errors shared via the package will appear in Flare with a "Share" button for easy distribution.

4. Customizing the Share URL:

   • Override the default URL structure by binding a custom URL generator to the Spatie\ErrorShare\ErrorShareUrlGenerator contract:

     $app->bind(\Spatie\ErrorShare\ErrorShareUrlGenerator::class, function ($app) {
         return new CustomUrlGenerator();
     });
     

5. Error Metadata:

   • Attach custom metadata to errors for debugging:

     ErrorShare::share(new \Exception('Error'), [
         'user_id' => auth()->id(),
         'context' => ['key' => 'value'],
     ]);
     

Gotchas and Tips

Pitfalls

1. Middleware Placement:

   • Place ShareErrorMiddleware after ConvertEmptyToNullMiddleware and ConvertEmptyToNullMiddleware in $middleware to ensure errors are captured correctly. Misplacement may result in silent failures or duplicate errors.

2. Flare API Key:

   • If flare_api_key is set but Flare is unreachable, errors will still be stored locally but won’t sync. Check storage/logs/laravel-error-share.log for sync failures.

3. Error Expiration:

   • Shared errors expire after error_expiration_in_minutes (default: 1440 minutes/24 hours). Use php artisan error-share:prune to clean up old errors manually.

4. Sensitive Data:

   • By default, the package does not redact sensitive data (e.g., passwords, tokens). Use Laravel’s app.debug or custom error handlers to filter data before sharing:

     ErrorShare::share($exception, [
         'redact' => ['password', 'api_token'],
     ]);
     

5. Queue Workers:

   • If using queues, ensure the error-share:prune command runs periodically (e.g., via Laravel Scheduler) to avoid storage bloat.

Debugging Tips

1. Log Location:

   • Check storage/logs/laravel-error-share.log for sync errors or custom metadata issues.

2. Testing Locally:

   • Use php artisan error-share:share to test error sharing without triggering HTTP errors:

     php artisan error-share:share --error="[object] (Exception(code: 0): Test at ...)"
     

3. Custom Error Pages:

   • Override the default error view by publishing the view:

     php artisan vendor:publish --tag="error-share-views"
     

   • Modify resources/views/vendor/error-share/errors/show.blade.php.

4. Environment-Specific Config:

   • Use environment variables to toggle features (e.g., ERROR_SHARE_FLARE_ENABLED=false in .env).

5. Rate Limiting:

   • The package doesn’t include rate limiting by default. Add middleware like throttle to ShareErrorMiddleware if needed:

     'share-error' => \Spatie\ErrorShare\ShareErrorMiddleware::class . '@' . __DIR__ . '/middleware/throttle',
     

Extension Points

1. Custom Error Storage:

   • Extend the Spatie\ErrorShare\ErrorShareRepository contract to store errors in a database or external service:

     $app->bind(\Spatie\ErrorShare\ErrorShareRepository::class, function ($app) {
         return new CustomErrorRepository();
     });
     

2. Webhook Notifications:

   • Listen for error-shared events to send notifications (e.g., Slack, email):

     Event::listen(\Spatie\ErrorShare\Events\ErrorShared::class, function ($event) {
         // Send notification
     });
     

3. Dynamic Error Metadata:

   • Use a closure to dynamically generate metadata:

     ErrorShare::share($exception, function () {
         return ['user' => auth()->user()->name];
     });
     

4. API Endpoint for Sharing:

   • Create a dedicated endpoint to share errors via API:

     Route::post('/api/errors/share', function (Request $request) {
         $error = $request->input('error');
         ErrorShare::share(new \Exception($error), $request->input('metadata', []));
         return response()->json(['shared' => true]);
     });