Laravel Error Share Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-error-share --dev
   

   • Install as a dev dependency to avoid bloating production environments.

2. Trigger an Error:

   • Introduce a deliberate exception (e.g., 1/0 in a route or controller).
   • The package automatically injects a "Share Error" button into Laravel’s default error page.

3. Share the Error:

   • Click the button to generate a Flare-compatible shareable link (e.g., https://your-app.test/errors/12345).
   • Send the link to teammates or embed it in issue trackers (e.g., GitHub, Jira).

First Use Case

Debugging Collaboratively:

• A frontend developer reports a 500 error on a checkout page.
• Instead of screen-sharing, the backend team:
  1. Reproduces the error locally.
  2. Shares the generated link via Slack.
  3. Teammates click the link to see the full stack trace, request payload, and environment context in Flare.

Implementation Patterns

Core Workflow

1. Error Occurrence:

   • The package hooks into Laravel’s render method for exceptions (via App\Exceptions\Handler).
   • No manual configuration required for basic usage.

2. Shareable Link Generation:

   • The link includes:
     • Error ID (for Flare lookup).
     • Signed URL (to prevent tampering).
     • Environment metadata (Laravel version, PHP config, etc.).
   • Example:

     // Manually trigger (e.g., in a test or CLI command)
     \Spatie\ErrorShare\ErrorShare::share($exception);
     

3. Flare Integration:

   • Links open in Flare’s UI, showing:
     • Stack traces with file links (opens in IDE).
     • Request/response data (headers, payload, cookies).
     • Environment variables (redacted by default).
   • Requires Laravel Flare installed separately.

Advanced Patterns

Customizing the Share Button

Override the default Blade view (resources/views/vendor/error-share/share-button.blade.php) to:

• Change button text/position:

  <button class="custom-class" onclick="shareError('{{ $errorId }}')">
      Debug This →
  </button>
  

• Add conditional logic (e.g., hide in production):

  // In AppServiceProvider@boot()
  if (app()->environment('production')) {
      \Spatie\ErrorShare\ErrorShare::disable();
  }
  

Programmatic Sharing

Share errors from CLI commands, queues, or tests:

use Spatie\ErrorShare\ErrorShare;

// In a command
public function handle()
{
    try {
        // Risky operation
    } catch (\Exception $e) {
        ErrorShare::share($e);
        $this->info('Error shared: ' . ErrorShare::getShareUrl($e));
    }
}

Extending Error Data

Add custom context to shared errors:

// In AppServiceProvider@boot()
\Spatie\ErrorShare\ErrorShare::extend(function ($exception, $payload) {
    $payload['custom_data'] = [
        'user_id' => auth()->id(),
        'feature_flag' => config('flags.new_ui'),
    ];
});

API Endpoint for Errors

Expose errors via an API (e.g., for mobile apps):

Route::get('/errors/{id}', function ($id) {
    return \Spatie\ErrorShare\ErrorShare::getError($id);
})->middleware('auth');

Gotchas and Tips

Pitfalls

1. Flare Dependency:

   • The package only generates links; Flare must be installed to view errors.
   • Fix: Install Flare first:

     composer require spatie/laravel-flare-react --dev
     

2. Environment Variables:

   • Sensitive data (e.g., APP_KEY) is automatically redacted in Flare, but ensure .env is never committed.
   • Tip: Use php artisan config:clear after sharing if config changes.

3. Caching Issues:

   • Shared links expire after 24 hours (configurable via flare.error_share_expiration_minutes).
   • Workaround: Re-share the error or extend the TTL in config/flare.php.

4. Laravel 12+ Quirks:

   • Views may fail to compile if using Laravel 12.29+ (fixed in v1.0.6).
   • Solution: Run composer update spatie/laravel-error-share --dev.

5. Queue Jobs:

   • Errors in queued jobs won’t show the share button by default.
   • Fix: Use ErrorShare::share() in the job’s failed() method or a retry listener.

Debugging Tips

• Check the Error ID:

  • Links like /errors/abc123 must match Flare’s stored errors. If missing, the link 404s.
  • Debug: Run php artisan flare:list to verify errors exist in Flare.

• Disable for Production:

  • The button appears in all environments by default. Disable it in production:

    // config/flare.php
    'error_share' => [
        'enabled' => env('APP_ENV') !== 'production',
    ],
    

• Custom Error Pages:

  • If using a custom error view (e.g., resources/views/errors/500.blade.php), include the share button manually:

    @if(config('flare.error_share.enabled'))
        @include('vendor.error-share.share-button', ['errorId' => 'custom-id'])
    @endif
    

Extension Points

1. Modify Payload:

   • Override Spatie\ErrorShare\ErrorShare::getPayload() to include/exclude data:

     public static function getPayload(Exception $exception): array
     {
         $payload = parent::getPayload($exception);
         unset($payload['context']['session']); // Remove session data
         return $payload;
     }
     

2. Custom Storage:

   • Store errors in a database instead of Flare by implementing Spatie\ErrorShare\ErrorShareRepositoryInterface.

3. Link Expiration:

   • Change the default 24-hour expiry:

     // config/flare.php
     'error_share_expiration_minutes' => 1440, // 24 hours
     

4. Local Testing:

   • Test sharing locally by forcing Flare to store errors:

     // In a test
     \Spatie\Flare\Flare::storeError($exception);
     $url = \Spatie\ErrorShare\ErrorShare::share($exception);
     $this->assertStringContainsString('errors/', $url);
     

Performance Notes

• Minimal Overhead: The package adds ~50ms to error rendering (negligible for debugging).
• Production Impact: Disable in production to avoid exposing error details:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      if (app()->environment('production')) {
          \Spatie\ErrorShare\ErrorShare::disable();
      }
  }