Laravel Error Share Laravel Package

Getting Started

Minimal Steps

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 error in your Laravel application (e.g., 1/0 in a route or controller).
   • The package automatically injects a "Share" button into Laravel’s default error page.

3. Share the Error:

   • Click the "Share" button to generate a Flare-compatible URL (e.g., https://your-app.test/errors/123).
   • Copy the link and share it with teammates or paste it into Flare for deeper analysis.

First Use Case

Debugging Collaboratively:

• A developer hits an unexpected error in a local environment.
• Instead of screen-sharing or manually describing the issue, they:
  1. Click "Share" on the error page.
  2. Paste the URL into Slack/Teams or Flare.
  3. Teammates instantly see the stack trace, request data, and environment context without leaving their IDE.

Implementation Patterns

Core Workflows

1. Error Sharing in Development:

   • Default Behavior: The package hooks into Laravel’s exception handler (App\Exceptions\Handler) and appends a "Share" button to the error view (resources/views/errors/500.blade.php or similar).
   • Customization: Override the default view by publishing the package’s assets:

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

     Modify resources/views/vendor/error-share/share-button.blade.php to adjust styling or add context (e.g., project name).

2. Integration with Flare:

   • The generated URL points to a Flare-compatible endpoint (if Flare is installed, errors are auto-captured).
   • For non-Flare setups, the URL includes a base64-encoded error payload that can be decoded manually or via a custom endpoint.

3. Programmatic Sharing:

   • Manually trigger sharing for specific exceptions using the shareError helper:

     use Spatie\ErrorShare\ErrorShare;
     
     try {
         // Risky code...
     } catch (\Exception $e) {
         $shareUrl = ErrorShare::share($e);
         // Log $shareUrl or send via email/Slack.
     }
     

4. Environment-Specific Control:

   • Disable sharing in production by adding to .env:

     ERROR_SHARE_ENABLED=false
     

   • Restrict to specific environments (e.g., local only) via config:

     'enabled' => env('ERROR_SHARE_ENABLED', app()->environment('local')),
     

Advanced Patterns

1. Custom Error Data:

   • Attach additional context to shared errors by extending the ErrorShare facade:

     $shareUrl = ErrorShare::share($e)
         ->withData(['user_id' => auth()->id(), 'custom_tag' => 'api-integration']);
     

2. API Endpoint for Remote Sharing:

   • Create a route to handle shared errors remotely:

     Route::post('/api/errors/share', function (Request $request) {
         $errorData = base64_decode($request->input('error_data'));
         // Process or log $errorData.
     });
     

   • Use this to centralize error reporting across microservices.

3. Testing:

   • Mock the ErrorShare facade in tests to verify error handling:

     $this->partialMock(Spatie\ErrorShare\ErrorShare::class, function ($mock) {
         $mock->shouldReceive('share')->andReturn('http://test-url');
     });
     

Gotchas and Tips

Pitfalls

1. View Compilation Issues:

   • Problem: Laravel 12+ may fail to compile views if the package’s assets aren’t published.
   • Fix: Run php artisan view:clear or publish views explicitly:

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

2. Flare Dependency:

   • Problem: The package assumes Flare is installed for optimal functionality. Without Flare, shared URLs may not render as expected.
   • Workaround: Use the shareError helper programmatically to generate a payload for custom processing.

3. Environment Mismatches:

   • Problem: Shared URLs may include local environment details (e.g., APP_URL=http://localhost), which are useless to teammates.
   • Fix: Override the ErrorShare config to exclude sensitive data:

     'exclude_data' => ['request.headers', 'server.*'],
     

4. CSRF Token Errors:

   • Problem: If the share button is added to a form-heavy page, CSRF tokens may conflict.
   • Fix: Ensure the share button’s form uses the correct CSRF meta tag or exclude it via Blade:

     @csrf
     <x-error-share::share-button :exclude-csrf="true" />
     

Debugging Tips

1. Inspect the Payload:

   • Decode the URL’s error_data parameter to verify shared content:

     echo $(echo "http://example.com/errors/123" | grep -oP '(?<=error_data=).+') | base64 --decode | jq
     

2. Log Shared Errors:

   • Extend the ErrorShare service to log URLs:

     Spatie\ErrorShare\ErrorShare::macro('share', function ($exception) {
         $url = parent::share($exception);
         \Log::info("Error shared: $url", ['exception' => $exception]);
         return $url;
     });
     

3. Test Locally:

   • Use php artisan tinker to test sharing programmatically:

     try { 1/0; } catch (\Exception $e) {
         echo \Spatie\ErrorShare\ErrorShare::share($e);
     }
     

Extension Points

1. Custom Share Endpoint:

   • Override the default share URL logic by binding a custom service:

     $this->app->bind(\Spatie\ErrorShare\Contracts\ErrorSharer::class, function () {
         return new CustomErrorSharer();
     });
     

2. Add Metadata:

   • Extend the Error model used by the package to include project-specific fields:

     namespace Spatie\ErrorShare;
     
     class Error extends \Spatie\ErrorShare\Error {
         public function getProjectName(): string {
             return config('app.project_name', 'My App');
         }
     }
     

3. Localization:

   • Translate the share button text by publishing the language files:

     php artisan vendor:publish --tag=error-share-lang
     

     Then override in resources/lang/en/error-share.php:

     return [
         'share_button' => 'Send to Team',
     ];
     

4. Security:

   • Restrict sharing to authenticated users by adding middleware to the share route:

     Route::middleware(['auth'])->group(function () {
         // Share routes...
     });