Platform Widget Bundle Laravel Package

Getting Started

Minimal Steps to First Widget

1. Install the Bundle

   composer require digitalstate/platform-widget-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DigitalState\PlatformWidgetBundle\DigitalStatePlatformWidgetBundle::class => ['all' => true],
   ];
   

2. Define a Basic Widget Create a service in your bundle’s Resources/config/services.yaml:

   services:
       App\Widget\MyFirstWidget:
           tags:
               - { name: ds.widget, title: "My Widget", position: 100 }
   

3. Implement the Widget Logic Create a class implementing \DigitalState\PlatformWidgetBundle\Model\WidgetInterface:

   namespace App\Widget;
   
   use DigitalState\PlatformWidgetBundle\Model\WidgetInterface;
   
   class MyFirstWidget implements WidgetInterface
   {
       public function getContent(): string
       {
           return '<div>Hello, Widget!</div>';
       }
   }
   

4. Render Widgets in a Template Use the ds_widget Twig function in your template:

   {{ ds_widget('App\\Widget\\MyFirstWidget') }}
   

First Use Case: Dashboard Widget

Create a dashboard widget that displays user-specific stats:

# services.yaml
services:
    App\Widget\DashboardStatsWidget:
        tags:
            - { name: ds.widget, title: "User Stats", position: 50, context: "dashboard" }

// DashboardStatsWidget.php
public function getContent(): string
{
    $user = auth()->user();
    return view('widgets.dashboard-stats', ['user' => $user])->render();
}

Implementation Patterns

Widget Organization

1. Grouping Widgets Use service tags with group attribute to organize widgets:

   tags:
       - { name: ds.widget, group: "admin", title: "Admin Tools", position: 10 }
   

   Render all widgets in a group:

   {% for widget in ds_widgets('admin') %}
       {{ widget.getContent() }}
   {% endfor %}
   

2. Context-Based Widgets Filter widgets by context (e.g., dashboard, sidebar):

   tags:
       - { name: ds.widget, context: "sidebar", title: "Quick Actions" }
   

   Render context-specific widgets:

   {{ ds_widgets('sidebar')|ds_widget_filter('user.is_admin') }}
   

Dynamic Content

1. Dependency Injection Inject services into widgets for dynamic data:

   use App\Services\UserStatsService;
   
   class UserStatsWidget implements WidgetInterface
   {
       public function __construct(private UserStatsService $statsService) {}
   
       public function getContent(): string
       {
           return $this->statsService->getDashboardStats();
       }
   }
   

2. Twig Integration Pass data to Twig templates:

   public function getContent(): string
   {
       return view('widgets.user-card', ['user' => auth()->user()])->render();
   }
   

Workflows

1. Widget Lifecycle

   • Registration: Tag services with ds.widget.
   • Rendering: Use ds_widget() or ds_widgets() in Twig.
   • Caching: Enable caching via ds_widget_cache Twig function if needed.

2. Admin Panel Integration Create an admin widget to manage widget positions:

   tags:
       - { name: ds.widget, title: "Widget Manager", position: 200, admin: true }
   

Gotchas and Tips

Pitfalls

1. Service Tagging

   • Issue: Widgets not appearing? Verify the service is tagged with ds.widget.
   • Fix: Check services.yaml and clear cache:

     php artisan cache:clear
     

2. Context Filtering

   • Issue: Context filters (e.g., ds_widget_filter) may not work if the context is not defined in the widget tag.
   • Fix: Ensure context is specified in the tag:

     tags:
         - { name: ds.widget, context: "dashboard" }
     

3. Circular Dependencies

   • Issue: Widgets depending on other widgets may cause circular references.
   • Fix: Use lazy loading or resolve dependencies via the container:

     $this->container->get(MyService::class);
     

Debugging

1. List All Widgets Dump registered widgets in Twig:

   {{ dump(ds_widgets()) }}
   

2. Check Widget Existence Verify a widget is registered:

   $widget = $this->container->get('ds.widget.manager')->get('App\Widget\MyWidget');
   if (!$widget) {
       throw new \RuntimeException('Widget not found!');
   }
   

Extension Points

1. Custom Widget Manager Extend \DigitalState\PlatformWidgetBundle\Manager\WidgetManager to add logic:

   class CustomWidgetManager extends WidgetManager
   {
       public function getFilteredWidgets(string $context, array $filters = [])
       {
           // Custom filtering logic
           return parent::getFilteredWidgets($context, $filters);
       }
   }
   

2. Widget Events Listen to widget events (e.g., ds.widget.render):

   use DigitalState\PlatformWidgetBundle\Event\WidgetRenderEvent;
   
   $dispatcher->addListener(WidgetRenderEvent::class, function (WidgetRenderEvent $event) {
       // Modify widget content dynamically
       $event->setContent($event->getContent() . '<div>Appended content</div>');
   });
   

Performance Tips

1. Cache Widgets Enable caching for static widgets:

   {{ ds_widget_cache('App\\Widget\\StaticWidget', 3600) }}
   

2. Lazy-Load Heavy Widgets Defer initialization of resource-intensive widgets:

   public function getContent(): string
   {
       if (!$this->content) {
           $this->content = $this->loadHeavyData();
       }
       return $this->content;
   }
   

Configuration Quirks

1. Position Overrides Override widget positions dynamically via config:

   # config/packages/ds_widget.yaml
   ds_widget:
       positions:
           'App\Widget\MyWidget': 50
   

2. Twig Extensions Extend the Twig environment to add custom filters:

   $twig->addExtension(new class extends \Twig\Extension\AbstractExtension {
       public function getFilters()
       {
           return [
               new \Twig\TwigFilter('ds_widget_filter', [$this, 'filterWidgets']),
           ];
       }
   });