Laravel Telescope Toolbar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require fruitcake/laravel-telescope-toolbar
   

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

   php artisan vendor:publish --provider="Fruitcake\TelescopeToolbar\TelescopeToolbarServiceProvider"
   

2. Enable the Toolbar Add the middleware to your app/Http/Kernel.php:

   protected $middlewareGroups = [
       'web' => [
           // ...
           \Fruitcake\TelescopeToolbar\Middleware\TelescopeToolbar::class,
       ],
   ];
   

3. First Use Case

   • Visit any route in your Laravel app. The Telescope toolbar will appear at the bottom of the page (default).
   • Click the toolbar to expand and view:
     • Request details (headers, method, URI).
     • Response time and status.
     • Telescope entries (if any) for the current request.
     • Quick links to Telescope’s dashboard or entry details.

Implementation Patterns

1. Customizing Toolbar Appearance

• Positioning: Modify config/telescope-toolbar.php to change the toolbar’s position (e.g., top-right):

  'position' => 'top-right',
  

• Styling: Override the Blade template (resources/views/vendor/telescope-toolbar/toolbar.blade.php) or use CSS:

  .telescope-toolbar { background: #2d3748; }
  

2. Conditional Display

• Hide for Specific Routes:

  // In Kernel.php
  \Fruitcake\TelescopeToolbar\Middleware\TelescopeToolbar::except([
      'admin/*',
      'api/*',
  ]);
  

• Environment-Based Toggle:

  // config/telescope-toolbar.php
  'enabled' => env('APP_ENV') !== 'production',
  

3. Extending Functionality

• Add Custom Panels: Use the TelescopeToolbar::addPanel() method in a service provider:

  TelescopeToolbar::addPanel(
      'custom-panel',
      function () {
          return [
              'title' => 'My Custom Data',
              'content' => 'Hello from custom panel!',
          ];
      }
  );
  

• Hook into Telescope Events: Listen for telescope.toolbar.panels events to dynamically modify panels:

  event(new TelescopeToolbarPanels);
  

4. Integration with Telescope

• Link to Telescope Entries: The toolbar auto-links to relevant Telescope entries. Ensure Telescope is installed and configured:

  composer require laravel/telescope
  php artisan telescope:install
  

5. Performance Monitoring

• Track Slow Requests: Use the toolbar to identify bottlenecks. Click the "Response Time" panel to see execution time breakdowns.
• Log Custom Metrics: Add custom data to Telescope entries (e.g., queue jobs, external API calls) to appear in the toolbar:

  Telescope::log('custom_event', [
      'data' => 'value',
  ]);
  

Gotchas and Tips

Pitfalls

1. Toolbar Not Showing?

   • Ensure the middleware is registered in Kernel.php.
   • Verify Telescope is installed and the database is configured (config/telescope.php).
   • Check for JavaScript errors in the browser console (the toolbar relies on JS).

2. Double Toolbars

   • If using both laravel-debugbar and this package, disable one or configure them to avoid conflicts:

     'debugbar' => false, // in config/telescope-toolbar.php
     

3. Performance Overhead

   • The toolbar adds minimal overhead (~1-2ms per request). Disable in production:

     'enabled' => env('APP_ENV') !== 'production',
     

4. CSRF Token Mismatch

   • If the toolbar fails to load, ensure your routes are protected with the web middleware group (which includes CSRF protection).

Debugging Tips

• Check Telescope Entries: Visit /telescope to confirm entries are being logged for the current request.
• Inspect Network Requests: Use browser dev tools to verify the toolbar’s AJAX calls to /telescope-toolbar/data.
• Clear Cache:

  php artisan view:clear
  php artisan cache:clear
  

Extension Points

1. Custom Data in Panels Extend the TelescopeToolbarPanel class to create reusable panels:

   class MyPanel extends TelescopeToolbarPanel
   {
       public function title()
       {
           return 'My Panel';
       }
   
       public function content()
       {
           return '<div>Custom content</div>';
       }
   }
   

   Register it in a service provider:

   TelescopeToolbar::addPanel(new MyPanel());
   

2. Override Blade Templates Publish and modify the toolbar’s Blade templates:

   php artisan vendor:publish --tag=telescope-toolbar-views
   

3. Localization Translate toolbar labels by publishing the language files:

   php artisan vendor:publish --tag=telescope-toolbar-lang
   

   Then override resources/lang/vendor/telescope-toolbar/*.php.

Pro Tips

• Keyboard Shortcuts: Press ? to toggle the toolbar quickly (if using the default JavaScript).
• Dark Mode: Add this to your CSS for a dark-themed toolbar:

  .telescope-toolbar.dark-mode { background: #1a202c; color: white; }
  

• Exclude API Routes: Use the except method in the middleware to keep APIs clean:

  TelescopeToolbar::except(['api/*']);
  

• Log Only Errors: Combine with Telescope’s except to log only failed requests:

  Telescope::except([
      'telescope::*',
      'horizon::*',
  ]);