Hookshelper Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require agencetwogether/hookshelper
   

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

   php artisan vendor:publish --tag="hookshelper-config"
   

2. Register the Plugin: Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Agencetwogether\HooksHelper\HooksHelperPlugin::make(),
           ]);
   }
   

3. First Use Case:

   • Navigate to any Filament page (e.g., a resource list or create/edit page).
   • Look for the Hooks Helper toggle button (default: top-right corner).
   • Toggle it on to reveal all available render hooks for the current page in a collapsible sidebar.

Where to Look First

• Default Placement: The toggle button appears in the top-right corner of Filament pages by default. Check the config file (config/hookshelper.php) to adjust its position or visibility.
• Hooks Display: After toggling, hooks are displayed in a sidebar with their names, slots, and (if applicable) associated components. Use this to:
  • Understand where to inject custom UI elements.
  • Debug rendering issues by inspecting hook availability.
• Documentation: The README’s Usage section covers placement, icons, and minification toggles.

Implementation Patterns

Core Workflows

1. Debugging Render Hooks:

   • Use the toggle to inspect hooks during development. For example, if you’re building a custom Filament widget and need to inject content into a specific section (e.g., RecordTable.BulkActions), toggle the helper to confirm the hook exists and its exact name.
   • Example:

     // In a Filament widget or page:
     use Agencetwogether\HooksHelper\Facades\HooksHelper;
     
     HooksHelper::addHook('RecordTable.BulkActions', view('filament.custom-bulk-actions'));
     

2. Dynamic Hook Injection:

   • Leverage hooks to conditionally render UI elements. For instance, add a hook to the Page.Header slot only on specific pages:

     if (request()->routeIs('filament.pages.custom-page')) {
         HooksHelper::addHook('Page.Header', view('filament.custom-header'));
     }
     

3. Testing Hooks:

   • Use the helper to verify hooks are registered correctly in tests. For example, in a FeatureTest:

     public function test_hook_is_registered()
     {
         $response = $this->get('/filament/resources/posts');
         $response->assertSee('RecordTable.BulkActions'); // Check if hook exists via UI
     }
     

Integration Tips

1. Customizing the Toggle Button:

   • Modify the button’s icon or placement via the config:

     // config/hookshelper.php
     'icon' => 'heroicon-o-cog', // Default: 'heroicon-o-code-bracket'
     'placement' => 'top-right', // Options: 'top-left', 'bottom-left', 'bottom-right'
     

2. Minification Toggle:

   • Enable/disable minified hook display in the config to reduce clutter:

     'minify' => env('HOOKSHELPER_MINIFY', false),
     

3. Extending Hooks:

   • Register global hooks in a service provider:

     public function boot()
     {
         HooksHelper::addGlobalHook('GlobalFooter', view('filament.global-footer'));
     }
     

4. Conditional Hooks:

   • Use middleware or route checks to enable hooks only in specific contexts (e.g., app/Providers/HooksHelperServiceProvider.php):

     if (app()->environment('local')) {
         HooksHelper::enable();
     }
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Issue: Enabling hooks in production can slow down page loads due to additional DOM elements and logic.
   • Fix: Disable hooks in non-local environments via config:

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

2. Hook Naming Conflicts:

   • Issue: Custom hooks with the same name as Filament’s built-in hooks may override them unintentionally.
   • Fix: Prefix custom hooks (e.g., custom.RecordTable.BulkActions) or verify uniqueness via the helper’s UI.

3. Caching:

   • Issue: Hooks may not update immediately if Filament’s cache is enabled (e.g., php artisan filament:cache).
   • Fix: Clear the cache after adding hooks:

     php artisan filament:cache-clear
     

4. Hook Scope:

   • Issue: Hooks registered in a service provider may not appear in the helper if they’re not tied to a specific page or component.
   • Fix: Register hooks in the getPages() or getWidgets() methods of Filament resources/pages.

Debugging Tips

1. Inspecting Hooks:

   • Use browser dev tools to inspect the rendered hooks sidebar. Look for the data-hook-name attribute to confirm hook names.
   • Example: Right-click the sidebar → Inspect → Search for hookshelper.

2. Logging Hooks:

   • Enable debug logging in config/hookshelper.php:

     'debug' => true,
     

   • Check storage/logs/laravel.log for hook registration events.

3. Disabling Specific Hooks:

   • Exclude hooks from the helper’s display via config:

     'exclude_hooks' => [
         'filament.admin.*', // Exclude all admin-related hooks
         'custom.ignored-hook',
     ],
     

4. Testing Hooks in CI:

   • Mock the helper in tests to avoid flakiness:

     HooksHelper::shouldReceive('getHooks')->andReturn(['test.hook' => 'Test Hook']);
     

Extension Points

1. Custom Hook Providers:

   • Create a custom provider to extend hook functionality:

     namespace App\Providers;
     
     use Agencetwogether\HooksHelper\Contracts\HookProvider;
     use Illuminate\Support\Facades\Blade;
     
     class CustomHookProvider implements HookProvider
     {
         public function register()
         {
             HooksHelper::addHook('Page.Header', function () {
                 Blade::render('filament.custom-header');
             });
         }
     }
     

   • Register it in config/hookshelper.php:

     'providers' => [
         \App\Providers\CustomHookProvider::class,
     ],
     

2. Hook Events:

   • Listen for hook registration events to trigger side effects:

     use Agencetwogether\HooksHelper\Events\HookRegistered;
     
     HookRegistered::listen(function (HookRegistered $event) {
         logger()->info("Hook registered: {$event->hookName}");
     });
     

3. Localization:

   • Translate hook names or descriptions by publishing the language files:

     php artisan vendor:publish --tag="hookshelper-lang"
     

   • Extend resources/lang/vendor/hookshelper.php:

     return [
         'hooks' => [
             'custom.hook' => 'Custom Hook (Translated)',
         ],
     ];