Widgets Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. Before you composer require anything, confirm the project you're working in is a Symfony app (or a hybrid where Symfony components are bootstrapped alongside Laravel). If you're purely in Laravel, treat this as a reference implementation to port rather than a drop-in dependency.

1. Install

   composer require splash/widgets-bundle
   

   Then enable it in config/bundles.php (Flex) or your kernel:

   BadPixxel\WidgetsBundle\BadPixxelWidgetsBundle::class => ['all' => true],
   

   (Verify the exact class name from the bundle's src/ — the repo's namespace is the source of truth.)

2. Look here first

   • src/ — the abstract widget base class and any renderer/collection service. This tells you the contract you extend.
   • Resources/config/services.yaml (or config/) — service tags and the renderer service id.
   • Resources/views/ — the default Twig templates you'll override for styling.
   • The README's example widget — copy it verbatim as a smoke test.

3. First use case: a dashboard "info box" Create one concrete widget class (title, icon, value, colour), register it, render it on a page, and confirm it appears. Do not start by building five widgets — get one end-to-end render working first, because registration/tagging is where this bundle will bite you.

Implementation Patterns

• Class-per-widget. Extend the bundle's base widget class, supply the data and the template. Dynamic widgets (queries, API calls) live in PHP; static info boxes can be defined in config and rendered directly.
• Service registration + tagging. Register widgets as services and tag them so the collection/renderer can discover them. Use _instanceof autoconfiguration to tag every subclass of the base widget:

  _instanceof:
      BadPixxel\WidgetsBundle\Widget\AbstractWidget:
          tags: ['splash.widget']
  

• Render from the controller. Inject the renderer/collection service and hand it widget names plus parameters; return the rendered HTML to the view. Keeps widget instantiation testable.
• Render from Twig. For dashboards, a Twig function/extension (e.g. {{ render_widget('sales_kpi', {...}) }}) is the ergonomic path — but confirm the extension is enabled, since it may be optional.
• Compose, don't nest. Widgets should render a single card/box. Lay them out in a Bootstrap grid in the parent template; don't let widgets own page layout.
• Config-driven for trivial boxes. Static text/icon/link boxes are usually cheaper to declare in YAML than to write a class for.
• Testing. Functional-test one widget: boot the kernel, call the renderer, assert the HTML contains the expected value. That catches template + service-wiring regressions cheaply.

Gotchas and Tips

• Framework mismatch is the big one. There is no service provider, no facade, no config/widgets.php. Porting to Laravel means re-implementing the renderer as a singleton, converting service tags to a container binding, and rewriting Twig templates as Blade. Budget for that if you're Laravel-only.
• Abandonment risk. 1 star / 0 dependents means you are effectively the maintainer. Pin the exact version in composer.json, commit the lockfile, and be prepared to fork. Check the bundle's composer.json for the Symfony and PHP version constraints before assuming it installs on a modern stack.
• Widgets don't show up? Run bin/console debug:container --tag=<the-tag>. Usually it's a missing tag, a class outside the autoconfigured namespace, or a stale cache after registering.
• Cache. Always bin/console cache:clear after adding or renaming a widget; collections are frequently compiled.
• Template overrides. Use the standard Symfony bundle override path (templates/bundles/<BundleName>/...) rather than editing vendor/. Vendor edits vanish on the next composer update.
• Asset expectations. Default templates often assume Bootstrap and an icon font (FontAwesome). Either include them or override the templates — otherwise your "info boxes" ship unstyled.
• Extension point worth adding early. Write your own App\Widget\BaseWidget extending the package's abstract class, standardising colours, spacing, and the template path. Every widget then extends yours, so swapping out the package later is a one-file change instead of twenty.