Widgets Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require brouzie/widgets-bundle
   

   Register the bundle in config/app.php under providers:

   Koc\BrouzieWidgetsBundle\BrouzieWidgetsBundle::class,
   

2. Publish Config & Assets Run:

   php artisan vendor:publish --provider="Koc\BrouzieWidgetsBundle\BrouzieWidgetsBundle" --tag="config"
   

   This generates a config/brouzie_widgets.php file. Update paths, widget storage, and caching settings as needed.

3. First Widget Creation Use the make:widget Artisan command:

   php artisan make:widget MyFirstWidget
   

   This generates:

   • A WidgetService class (handles logic).
   • A WidgetView (Blade template).
   • A WidgetConfig (for configurable options).

4. Register the Widget Add your widget to config/brouzie_widgets.php under widgets:

   'widgets' => [
       'my_first_widget' => [
           'class' => \App\Widgets\MyFirstWidget::class,
           'label' => 'My First Widget',
           'configurable' => true, // If it has options
       ],
   ],
   

5. Render a Widget In a Blade template or controller:

   {{ widget('my_first_widget', ['option1' => 'value1']) }}
   

   Or programmatically:

   $widget = app(\Koc\BrouzieWidgetsBundle\WidgetManager::class)->render('my_first_widget', ['option1' => 'value1']);
   

Implementation Patterns

1. Widget Lifecycle

• Service Layer: Extend \Koc\BrouzieWidgetsBundle\AbstractWidget to define logic.

  namespace App\Widgets;
  
  use Koc\BrouzieWidgetsBundle\AbstractWidget;
  
  class MyFirstWidget extends AbstractWidget {
      public function getView(): string {
          return 'widgets.my_first_widget'; // Blade path
      }
  
      public function configure(array $config): void {
          $this->options = $config;
      }
  }
  

• View Layer: Use Blade templates (e.g., resources/views/widgets/my_first_widget.blade.php). Access options via $widget->options.

2. Dynamic Configuration

• Admin Panel Integration: Use the bundle’s WidgetConfig to expose options in a CMS-like interface. Example config:

  protected function getConfigFields(): array {
      return [
          'title' => ['type' => 'text', 'label' => 'Widget Title'],
          'color' => ['type' => 'select', 'options' => ['red', 'blue']],
      ];
  }
  

• Frontend Rendering: Pass dynamic data when rendering:

  {{ widget('my_first_widget', $pageConfig->widgetOptions) }}
  

3. Caching Strategies

• Cache Widget Output: Enable caching in config/brouzie_widgets.php:

  'cache' => [
      'enabled' => true,
      'ttl' => 3600, // 1 hour
  ],
  

• Invalidate Cache: Use WidgetManager::clearCache('widget_name') after updates.

4. Reusability Patterns

• Shared Widgets: Store widgets in a database (extend WidgetRepository).
• Theming: Override widget views per theme by namespacing Blade paths (e.g., themes/dark/widgets/my_first_widget.blade.php).

5. Integration with Laravel Ecosystem

• Service Providers: Bind custom widget repositories or managers.

  $this->app->bind(
      \Koc\BrouzieWidgetsBundle\WidgetRepository::class,
      \App\Repositories\CustomWidgetRepository::class
  );
  

• Events: Listen for WidgetRendering events to modify output globally.

Gotchas and Tips

Pitfalls

1. Widget Registration Order:

   • Widgets must be registered in config/brouzie_widgets.php before first use. Lazy-loading isn’t supported.
   • Fix: Ensure the config file is loaded early (e.g., via BootstrapServiceProvider).

2. Blade Template Paths:

   • The bundle assumes widgets live in resources/views/widgets/. Custom paths require overriding getView() or configuring view_path in the config.
   • Tip: Use relative paths (e.g., '../widgets/my_widget') if organizing views differently.

3. Circular Dependencies:

   • Avoid calling widget() inside a widget’s configure() method to prevent infinite loops.
   • Workaround: Use dependency injection for nested widgets.

4. Configurable Widgets Without Options:

   • Setting 'configurable' => true but not defining getConfigFields() will throw errors.
   • Fix: Either implement getConfigFields() or set 'configurable' => false.

5. Database Storage Quirks:

   • If using database-backed widgets, ensure the widgets table exists and matches the bundle’s migrations (or extend WidgetRepository to handle custom schemas).

Debugging Tips

• Check Registered Widgets: Dump the widget list in a route:

  dd(app(\Koc\BrouzieWidgetsBundle\WidgetManager::class)->getWidgets());
  

• View Rendering Issues: Verify Blade templates exist and are cache-busted (php artisan view:clear).
• Configuration Errors: Validate config/brouzie_widgets.php for typos in widget class names or paths.

Extension Points

1. Custom Storage: Override WidgetRepository to store widgets in a NoSQL database or API.

   class ApiWidgetRepository extends WidgetRepository {
       public function find($name) {
           return $this->fetchFromExternalApi($name);
       }
   }
   

2. Widget Events: Dispatch events in AbstractWidget:

   event(new WidgetRendering($this));
   

   Listen globally in EventServiceProvider.

3. Dynamic Widget Loading: Implement WidgetLoaderInterface to load widgets from a remote service or cache.

4. Security: Add middleware to validate widget configurations:

   $widget->options = $this->sanitizeOptions($config);
   

Performance Optimizations

• Pre-render Widgets: Use WidgetManager::preRender() to cache output during low-traffic periods.
• Lazy-Load Heavy Widgets: Defer initialization of resource-intensive widgets until needed.
• Asset Optimization: Bundle widget CSS/JS separately and use Laravel Mix/Vite for concatenation.