Filawidget Laravel Package

Getting Started

Minimum path from zero to a rendered dynamic widget:

composer require ibrahimbougaoua/filawidget
php artisan vendor:publish --provider="IbrahimBougaoua\Filawidget\FilawidgetServiceProvider"
php artisan migrate

Register the plugin on the panel you want it on, in your PanelProvider:

->plugin(FilawidgetPlugin::make())

Where to look first, in order:

1. The README's "Usage" block — the package is small (10 stars, single maintainer) and the README is effectively the spec.
2. src/ for the core widget/content model and its Filament resource — this is the contract you will be extending.
3. config/filawidget.php (if published) — layout, ordering, visibility and rendering options live here.
4. The published migrations — confirm table names and foreign keys before you add your own relations.

First use case: a dashboard or page section whose content is edited by a non-developer. Create a widget record through the Filament UI, attach it to a panel/page position, and render it in a Blade view. Treat it as a "content block" store rather than as a widget framework — that is where the package's value sits.

Implementation Patterns

Content-block CMS pattern (primary). Keep the package's model as the source of truth for editable sections. Put a HasWidgets-style relation or a query scope on the model that owns the page (a Page, Post, or panel), then render <x-filawidget::render :widget="$widget" /> (verify the exact tag in the README) inside your layout. This lets editors reorder, hide, and retitle blocks without a deploy.

Panel-scoped registration. Register the plugin only on the admin panel. If you run multiple panels (admin + tenant), scope the widget query by the current panel/tenant ID; otherwise editors on one tenant will see another's content.

Seeding and fixtures. Seed default widgets in a seeder so fresh environments and tests aren't empty. This is also the cheapest way to make the package testable — assert on rendered HTML rather than on internal methods.

Custom block types. For anything beyond text/HTML, extend the base widget type (or add a type column plus a Blade partial) and register the mapping in config. Keep rendering as Blade partials keyed by type, not as model methods, so designers can iterate without touching PHP.

Ordering and visibility. Use the package's ordering column for drag-and-drop and a boolean is_visible/publish flag for staged content. Do not rely on created_at ordering.

Integration with your app's content. Store a polymorphic owner (model_type, model_id) if the package doesn't already, so widgets can be attached to pages, products, or the dashboard without schema changes later.

Gotchas and Tips

• Maintenance risk is real. One maintainer, last release September 2024, 10 stars. Pin the version in composer.json and expect to vendor-patch if Filament bumps a major version before this package does. Check the composer.json constraint against your Filament version (v2 vs v3 differences are breaking) before committing.
• Filament version drift. Filament's resource and widget APIs changed between v2 and v3. If the README targets v2, expect to adjust namespaces (Filament\Resources vs Filament\Resources\Resource) and form schema calls yourself.
• Migrations are the sharp edge. Published migrations often collide with an existing widgets/content table. Read the file before running migrate; rename tables in the migration rather than after the fact.
• Config cache. After changing config/filawidget.php or adding a block type, run php artisan config:clear and php artisan filament:cache-components (or optimize:clear). Silent render failures are usually stale config or a cached component registry.
• Rendering failures are quiet. If a widget renders blank, check in this order: the record exists and is visible, the Blade view is resolvable, the block type is registered in config, and the panel actually has the plugin. Add a temporary @dump($widget) in your partial.
• Extension points. Prefer config-driven registration (block types, views, ordering field) over subclassing internals. Your override surface should be: published views, published config, and a thin wrapper model — not the package's resource classes.
• Asset publishing. If the package ships JS/CSS for drag-and-drop ordering, you must re-run vendor:publish and filament:assets after every upgrade; a stale asset bundle shows ordering as broken with no console error.
• Testing. Write a feature test that creates a widget and asserts the rendered HTML contains the expected block. Abstract the package behind a small WidgetRenderer contract so you can swap it out if maintenance stalls — this is the single highest-value thing you can do given the score.