Filament Tag Manager Laravel Package

Getting Started

• composer require rawshan008/filament-tag-manager:^1.0 — pin the major. This is the first stable release, and the v1.0.0 notes contain nothing but a changelog link, so there is no documented API contract yet; treat 1.0.0 as the baseline you diff future tags against.
• Because the release notes carry no migration/upgrade detail, your source of truth is the repo: README.md, composer.json (require block for Filament/Laravel/PHP constraints), src/, and database/migrations/. Read those before running anything.
• Standard install path to expect: publish config and migrations (php artisan vendor:publish --tag="filament-tag-manager-config" and ...-migrations), review the published config (table names, model overrides, morph map key), then php artisan migrate.
• Confirm Filament major compatibility first. Filament plugins are usually written against one major (v3 or v4); a mismatch shows up as missing Filament\Forms\Components classes or a plugin class that fails to satisfy the contract.
• If the package ships a plugin class, register it in your panel provider (->plugin(TagManagerPlugin::make())) and check whether it auto-registers a TagResource; if it doesn't, scaffold your own resource against the package's Tag model.
• First use case: tag an existing model (e.g. Post) — drop the package's tag form component into PostResource::form() and its badge/column into the table, then confirm the pivot rows land in the tags table. Do this before touching the tag vocabulary UI so you validate the polymorphic wiring early.

Implementation Patterns

• Attach-to-existing-model as the default path. Treat the package as a tag field + vocabulary resource for models you already have, not as a standalone tagging app. Add the relationship trait/interface the README specifies to Post, and keep the package's Tag model untouched unless you need behaviour changes (extend via config model override rather than editing vendor files).
• Admin vocabulary, editor assignment. Create tags through the TagResource (with policies limiting create/delete to admins), and restrict editors to selecting existing tags in the form component. This keeps the taxonomy clean and avoids typo-duplicates like Laravel / laravel / laravel .
• Create-on-the-fly, scoped. If the tag component exposes Filament's createOptionForm() / searchable() options, enable creation for trusted roles only. Pair it with a unique index on the tag slug in a follow-up migration if the package doesn't ship one.
• Filtering in tables. Wire the package's filter (or a SelectFilter::make('tags')->relationship('tags', 'name')) into list tables; this is the highest-value day-to-day integration — tagging is only useful when you can slice index pages by it.
• Seeding. Seed a canonical tag set in a seeder and have the form component's options resolve from the database, so local/staging/production panels share the same vocabulary.
• Querying outside Filament. For reports and APIs, use the relationship directly: Post::whereHas('tags', fn ($q) => $q->whereIn('slug', $slugs)), always eager-loading with('tags') to avoid N+1 in resources and API transformers.
• Multi-tenancy. If tags should be tenant-scoped, add a tenant_id to the tags table and a global scope on your extended model — do this before production data exists, since the polymorphic pivot makes retrofitting messy.

Gotchas and Tips

• No documented surface area. v1.0.0's release notes are just a changelog URL, so there are no stated breaking changes, deprecations, or feature list. Before adopting, skim the commit history for the config keys and public class names, and snapshot the version in composer.lock.
• Polymorphic type column = morph alias. The package almost certainly stores taggable_type; if you later call Relation::enforceMorphMap(), existing rows keep the old FQCN and silently stop resolving. Set the morph map before tagging, or write a data migration.
• Model renames break links. Same trap from the other direction: renaming App\Models\Post orphans every tag association for it.
• Slug uniqueness and soft deletes. If tags are soft-deletable, a unique slug index blocks re-creating a tag with a previously deleted name. Use a partial index or restore-instead-of-create behavior.
• N+1 on badges. Rendering a tag column for 50 rows without ->with('tags') (or Filament's modifyQueryUsing) is a classic 50-query page. Check the query log on the list page during setup.
• Cache invalidation. If you cache the tag options list for form dropdowns, flush it in the Tag model's saved/deleted events — otherwise new tags don't appear in the panel until the TTL expires, which reads as a bug.
• Pivot cascade. Verify the published migration declares onDelete('cascade') on the taggable foreign key; if not, deleting a tag leaves orphan pivot rows that show up as empty badges.
• Publishing is one-way. Once you publish and hand-edit migrations or the config, future package updates won't touch them — record in your README which files are locally modified so the next upgrade diff is cheap.
• Extension points to prefer: config overrides (model, table names), policy classes for the tag resource, and Filament component options for behaviour. Editing vendor/rawshan008/... guarantees a painful upgrade once 1.0.x patches land.