Ignition Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require facade/ignition --dev
   

   Ignition is automatically detected by Laravel and requires no manual configuration for basic usage.

2. First Use Case: Trigger an exception in your Laravel application (e.g., 1/0 in a route or controller). Ignition will replace Laravel’s default error page with an interactive, detailed exception page.

3. Where to Look First:

   • Exception Page: Focus on the stack trace (highlighted line in your code) and context panels (request, response, environment).
   • Solution Suggestions: Ignition often provides actionable fixes for common errors (e.g., missing config, route issues).
   • Code Preview: Click the file/line in the stack trace to jump directly to the relevant code in your IDE (if using Laravel IDE Helper).

Implementation Patterns

Usage Patterns

1. Debugging Workflow:

   • Trigger → Inspect → Fix:
     1. Reproduce the error in your browser.
     2. Use the context panels to drill into request data (e.g., POST payload, headers, cookies).
     3. Click the stack trace to see the exact line of code causing the issue.
     4. Use solution suggestions (if available) to resolve the problem.
   • Example:

     // In a route or controller:
     $user = User::findOrFail($id); // Triggers Ignition if $id is invalid.
     

     Ignition will show:
     • The query executed.
     • The invalid $id value.
     • Suggested fixes (e.g., "Check if the ID exists in the database").

2. Environment-Specific Debugging:

   • Ignition automatically hides sensitive data (e.g., passwords, API keys) in production-like environments (e.g., .env values).
   • Use the environment panel to verify loaded config values.

3. Sharing Errors:

   • Enable shareable error reports in config/ignition.php:

     'share' => [
         'enabled' => true,
         'host' => env('IGNITION_SHARE_HOST'),
     ],
     

   • Share the generated URL with your team for collaborative debugging.

4. Customizing Exception Handling:

   • Extend Ignition’s behavior by publishing its config:

     php artisan vendor:publish --provider="Facade\Ignition\IgnitionServiceProvider"
     

   • Modify config/ignition.php to:
     • Hide/show specific context panels.
     • Add custom solution suggestions for your app’s common errors.

5. Integration with Testing:

   • Use Ignition in local testing environments to debug failed tests.
   • Combine with Laravel’s --verbose flag for CLI errors:

     php artisan test --verbose
     

6. IDE Integration:

   • Install Laravel IDE Helper to enable clickable stack traces that open files in your IDE.
   • Configure ignition.php to include IDE-specific metadata:

     'ide' => [
         'enabled' => true,
     ],
     

Gotchas and Tips

Pitfalls

1. Production vs. Development:

   • Ignition is only active in development by default. Ensure APP_ENV=local in your .env to see Ignition pages.
   • Gotcha: Forgetting to set APP_DEBUG=true in .env will show Laravel’s default error page instead.

     APP_ENV=local
     APP_DEBUG=true
     

2. Sensitive Data Exposure:

   • Ignition redacts sensitive data (e.g., passwords, tokens) in .env files by default.
   • Gotcha: If you accidentally expose an .env file in a shared error report, ensure IGNITION_REDACTED_ENV_VARS in ignition.php includes all secrets:

     'redacted_env_vars' => [
         'APP_KEY',
         'DB_PASSWORD',
         'MAIL_PASSWORD',
     ],
     

3. Caching Issues:

   • Ignition’s exception pages are not cached. However, if you’re using a reverse proxy (e.g., Nginx), ensure it doesn’t cache error responses.
   • Fix: Add this to your Nginx config:

     fastcgi_cache_bypass $http_x_ignition;
     proxy_cache_bypass $http_x_ignition;
     

4. Custom Exception Handling:

   • If you override Laravel’s exception handler (App\Exceptions\Handler), ensure it does not swallow exceptions that Ignition should handle.
   • Gotcha: Avoid returning response()->json() or response()->view() in render() without letting Ignition process the exception first.

5. Asset Loading:

   • Ignition’s CSS/JS assets are loaded via Laravel’s mix. If you’re not using Mix, ensure the assets are published:

     php artisan vendor:publish --tag=ignition-assets
     

6. Laravel Version Compatibility:

   • Ignition supports Laravel 5.8+. Older versions may require additional setup.
   • Gotcha: If using Laravel < 8, ensure you’re on Ignition v2.x.

Tips

1. Keyboard Shortcuts:

   • Use Ctrl+F (or Cmd+F on Mac) to search the exception page for specific variables or errors.
   • Click the copy button in context panels to quickly share data (e.g., request payload).

2. Custom Solution Suggestions:

   • Add app-specific fixes to config/ignition.php under solution_suggestions:

     'solution_suggestions' => [
         'App\\Exceptions\\InvalidUserException' => [
             'message' => 'User not found. Check if the user exists in the database.',
             'documentation' => 'https://your-app-docs.com/user-validation',
         ],
     ],
     

3. Debugging API Errors:

   • For API errors, use the response panel to inspect the raw JSON response and headers.
   • Enable ignition.php's show_response option to display the full response body:

     'show_response' => true,
     

4. Performance Debugging:

   • Use Ignition to inspect query logs (if enabled) in the context panels. Look for N+1 queries or slow SQL.
   • Enable query logging in AppServiceProvider:

     if (env('APP_DEBUG')) {
         DB::enableQueryLog();
     }
     

5. Local Development Setup:

   • Add this to your composer.json to ensure Ignition is only installed in local environments:

     "require-dev": {
         "facade/ignition": "^2.0"
     }
     

   • Use composer install --dev to include Ignition in local setups.

6. Extending Context Panels:

   • Add custom panels by extending Ignition’s Context classes. Example:

     // app/Providers/IgnitionServiceProvider.php
     use Facade\Ignition\Context\Context;
     
     public function boot()
     {
         Context::macro('customPanel', function () {
             return [
                 'title' => 'Custom Data',
                 'content' => '<pre>' . print_r($this->exception->customData, true) . '</pre>',
             ];
         });
     }
     

7. Disabling Ignition Temporarily:

   • Set APP_DEBUG=false in .env to disable Ignition (e.g., for staging environments).
   • Tip: Use environment variables to toggle Ignition dynamically:

     if (!app()->environment('local') && !env('IGNITION_ENABLED')) {
         $this->dontFlash();
     }