Category Laravel Package

Getting Started

1. Install the package and publish its assets/config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   php artisan vendor:publish --tag=<package>-migrations
   php artisan migrate
   

2. Look here first: the reference Filament classes CategoryTypeForm and CategoryTypesTable. They are the canonical example of how the package expects forms and tables to be composed, and v1.0.12 rewrote both (Flex layout removed, status component unified, table normalized). Copying them is the fastest way to a working screen.
3. First use case: add the categoryable morph to a model, render CategoryTypesTable inside a Filament resource, and use CategoryTypeForm for create/edit. That gives you a working categorized-entity CRUD in an afternoon.

⚠️ If you are upgrading from an earlier 1.0.x, read Gotchas and Tips before you run composer update — v1.0.12 contains two renames/removals.

Implementation Patterns

Polymorphic categorization (categoryable)

Attach and detach from either side of the relation. v1.0.12 tightened the "is this model actually categoryable?" check, so the package now fails fast instead of silently no-op'ing — make sure the trait is on the model and the model is persisted before syncing:

$post->categories()->sync($request->validated('category_ids'));

// Guard when the model may be unsaved (the optimized check is stricter now)
if ($post->exists && $post->isCategoryable()) {
    $post->categories()->sync($ids);
}

Enum-backed status with the unified palette

Status now runs through a single enum aligned to one colour palette, and CategoryTypesTable reads that enum directly for badge rendering. Pattern: never hardcode a colour in your table — cast the column to the enum and let the package resolve the colour. This is what makes the v1.0.12 alignment worth adopting: one enum, one palette, forms and tables stay in sync automatically.

Forms: drop your Flex layout

CategoryTypeForm no longer tiles fields with Flex; it composes plain Filament sections plus the shared status component. If you copied the old form into your app, migrate it by deleting the Flex wrapper and swapping your hand-rolled status select for the package component — otherwise your fork drifts from upstream on the next enum change.

Uploads: plainUpload

localUpload was renamed to plainUpload. Update any published form/component references. The rename is deliberate (the component was never really "local" — it wraps Filament's plain file upload), so alias the old name yourself if you need a grace period for other branches.

Keyword search across polymorphic types

New in v1.0.12: models expose keywordSearchFields, consumed by the package's polymorphic search. Opt a model in by declaring the columns you want matched:

class Post extends Model
{
    use Categoryable;

    /** @var array<int, string> */
    public array $keywordSearchFields = ['title', 'slug', 'excerpt'];
}

Use this instead of writing per-type whereLike closures — the search now walks registered types and applies each model's declared fields. Keep the list narrow; every entry is a LIKE on every search.

Gotchas and Tips

• Breaking: getSnSubjectHrefUrl removed from HasSnSubject. There is no replacement in the trait. If your views/API resources call it, add your own accessor on the model (or a snSubjectUrl() helper) before upgrading. Grep for getSnSubjectHrefUrl across app, views, and Blade components.
• Breaking: localUpload → plainUpload. No alias is shipped. Grep published views and any custom Filament components. Silent failure mode is a missing/broken upload field, not an exception.
• Colour drift after the enum alignment. The status enum now uses one palette. If you previously overrode badge colours (custom Filament theme, published table view, inline ->color() calls), those overrides will fight the enum. Remove them and, if you need a different palette, override the enum's colour map in one place.
• CategoryTypesTable was normalized. If you extended it, re-check your column overrides — the previous shape was flattened, so anything keyed to the old column ordering/naming will misbehave.
• Empty keywordSearchFields means "not searchable", not "search everything". Set it on every model you expect in results, or that type quietly drops out of polymorphic search.
• HasSnSubject cleanup — the trait is now purely about the SN relation/subject. If you relied on it for URL generation, that responsibility has moved back to your app.
• laravel-boost blade update is dev-only. The core.blade.php change affects the local AI-tooling guidelines file. It never ships to production and is safe to republish or discard; don't let it show up as a noisy diff in review.
• Debugging polymorphic lookups: dump Relation::morphMap() and the model's morph alias before chasing categoryable bugs — an unregistered alias is the usual culprit, and the tightened check surfaces it as a failure rather than a silent skip.
• Extension point: treat the enum and the two reference Filament classes as the upstream contract. Overriding colours or re-tiling the form locally is what caused friction in this release; prefer configuring the enum/table over forking them.