Filament Rating Laravel Package

Getting Started

v2.0.0 is a platform-compatibility release: the only functional change is Filament 4 + Tailwind CSS 4 support. The field API you already use is unchanged, so the "getting started" path depends entirely on which Filament major you're on.

• On Filament 4: composer require mokhosh/filament-rating:^2.0
• On Filament 3: stay on ^1.4 — v2 targets Filament 4 and its dependency constraints will not resolve against Filament 3.
• Requirements to check first in composer.json: PHP 8.2+, Laravel 11+, filament/filament:^4.0, and a Tailwind 4 toolchain if you compile a custom Filament theme.

Read the package README first, then the single field class in vendor/mokhosh/filament-rating/src/Components/Rating.php — that file is the documentation surface, since the public API is small.

First use case — a star rating on a model with an integer column:

// database/migrations/...
$table->unsignedTinyInteger('rating')->nullable(); // nullable = "not yet rated"

// app/Models/Review.php
protected $casts = ['rating' => 'integer'];

// app/Filament/Resources/ReviewResource.php
use Mokhosh\FilamentRating\Components\Rating;

Rating::make('rating')
    ->stars(5)
    ->allowZero()
    ->required(),

Verify option names (stars(), allowZero(), color()) against the README for your exact version before copy-pasting — the class methods on the field are the source of truth.

Implementation Patterns

Form + column pairing. The field only writes an integer; reading it back is plain Filament. For tables use a TextColumn with formatStateUsing(fn ($state) => $state . ' ★'), or a custom view column if you want rendered stars. Don't assume the package ships a table column — it's a form component.

Nullable vs zero. Two valid models, pick one deliberately:

• unsignedTinyInteger('rating')->nullable() + ->allowZero() → null means unrated, 0 means explicitly zero stars.
• ->default(0) non-nullable → simpler aggregation (AVG(rating)), but you lose the "no opinion yet" state.

Validation lives with the field. ->stars(5) controls the UI only; add ->rules(['integer', 'between:0,5']) (or min:0 max:5) so API/import writes can't exceed the visible star count. Keep the number in one constant/const so the field and rules can't drift.

Reactive side effects. Livewire round-trips make this field useful beyond storage — e.g. ->afterStateUpdated(fn ($state, Set $set) => $set('is_positive', $state >= 4)), or showing a "thanks for the feedback" section conditionally.

Filament 4 theming. If you use the default Filament theme, there's nothing to publish. If you have a custom theme (->viteTheme()), Tailwind 4's CSS-first config means the package's views are only scanned if you add them explicitly:

@import 'tailwindcss';
@source '../../../../vendor/mokhosh/filament-rating/resources/views';

Skip this and star icons/colors render unstyled after the upgrade — the most likely "it broke" symptom.

Testing. It's a normal Filament form component, so fillForm(['rating' => 4])->call('save')->assertHasNoFormErrors() and an assertion against the DB column covers it. Add one test asserting an out-of-range value is rejected by your rules, since the field won't enforce it alone.

Upgrade workflow (1.x → 2.0). Bump the constraint, run composer update mokhosh/filament-rating filament/filament, follow Filament's own v4 upgrade guide (php artisan filament:upgrade), rebuild frontend assets, then clear caches (php artisan optimize:clear). Expect no changes to your field definitions.

Gotchas and Tips

• The version split is the whole gotcha. v2 has no Filament 3 support. On a mixed estate (some apps on F3, some on F4) you must pin per-project: ^1.4 vs ^2.0. An unpinned ^1.0 || ^2.0 constraint will silently swap majors and can drag filament/filament with it.
• No deprecations to chase. Release notes show only CI/dependabot bumps plus PR #21 (Filament 4 + Tailwind 4). No renamed methods, no removed options — so if your upgrade breaks, suspect Filament 4 itself or stale compiled CSS, not this package.
• Stale CSS is the #1 false positive. After upgrading, run a hard rebuild (npm run build, clear browser cache, php artisan filament:assets if you publish assets). Unstyled stars almost always mean a stale Tailwind output, not a broken package.
• @source paths must be relative to the CSS file, and Tailwind 4 dropped content: [] from tailwind.config.js. Copying an old v3 config forward is a common mistake that yields a silently empty stylesheet for vendor views.
• Watch for string values from Livewire. Depending on how the input is wired, the state can arrive as "4" rather than 4. Cast on save or in the model to keep between:0,5 and AVG() behaving predictably.
• Colors are palette keys, not hex. Filament's color() expects something resolvable from the theme (e.g. primary, warning). Arbitrary hex values may not survive Tailwind 4's JIT scan — if you need a specific hue, define it in your theme and reference the key.
• Debugging hook: the field renders through the package's Blade view in vendor/mokhosh/filament-rating/resources/views. Inspect it before assuming a bug; ->extraAttributes(['class' => 'my-rating']) is usually enough to target and override styling without forking.
• Forking is cheap here. This is a small, single-component package with a low release cadence (v1.4.1 → v2.0.0, mostly bot PRs). If you need a behavior it doesn't expose — half-stars, RTL handling, a table column — extending the field class locally is a lower-risk move than waiting on upstream.