Nusa Filament Laravel Package

Getting Started

• Install with composer require for the package, then run the migrations/seeders it ships for administrative regions. Confirm the region tables are populated before touching any form — an empty NusaOptions cache makes every dropdown look broken.
• Publish the config (php artisan vendor:publish --tag=...) and check the region table names and model bindings first. Most integration problems are config key mismatches, not code.
• First use case: a Filament v3 form with a cascading province → regency → district → postal code selector. Start with one resource form, not a global replacement — you want to confirm the cascade and the postal code behaviour on a single screen before rolling it into infolists and tables.
• Verify your stack matches the supported matrix: Filament ^3.0, Laravel 10/11/12, PHP 8.1+. Anything older is unsupported as of v1.0.0 and you should not attempt a partial upgrade.

Implementation Patterns

• Cascading selects in Filament forms. Wire the parent fields with ->live() and use ->afterStateUpdated() to null out children. v1.0.0 fixes the postal code not resetting when province/regency/district changes, so you can rely on the built-in reset instead of hand-rolling ->afterStateUpdated(fn (Set $set) => $set('postal_code', null)) on every level.
• Reading options from NusaOptions. Use the package's option provider rather than querying region models directly. This is what benefits from the new in-memory static cache — calling it repeatedly inside a table column or infolist no longer triggers an N+1. If you previously memoised region lists yourself, remove that layer; two caches with different lifetimes is a debugging trap.
• Table columns and infolists. Where you only need to display a resolved region name, prefer the option/cache-backed lookup over lazy-loading relations. This is the main performance win in v1.0.0 and matters most on list pages with 50+ rows.
• Child dropdown query limits. With a parent selected, child dropdowns now apply tighter query limits. If you have custom option queries or searchable selects that expect a full unfiltered list, validate that results are still complete for your region sizes — especially in dense provinces.
• Testing. Use RefreshDatabase with a seeded (or fixture) region subset. Static caching in NusaOptions can leak between tests in the same process; if you assert on option counts, refresh the cache or isolate the affected tests.

Gotchas and Tips

• Static cache invalidation. The new in-memory cache in NusaOptions lives for the request/process. After seeding or editing region data in a long-running process (queue worker, Octane, artisan tinker), stale options will persist. Restart workers or call the cache reset if one is exposed.
• Postal code reset change is behavioural. If you had custom logic clearing postal code on parent change, it may now run twice or conflict with the package's reset. Remove your workaround and retest the cascade end to end.
• Cascade state on edit. Loading an existing record with a postal code set and then changing a parent region is the exact flow the bug fix targets — add a regression test for it, since it is easy to reintroduce via custom afterStateUpdated hooks.
• Query limits are a trade-off. The optimised child limits assume a parent is selected. Guard your form so child selects are disabled until the parent has a value, otherwise users may see empty or truncated lists and file it as a bug.
• Filament v3 only. Extension points (form component macros, custom field classes) are written against v3 APIs. If any part of your app is still on v2, keep that resource on a separate branch — there is no compatibility shim.
• Debugging tip. When a dropdown is empty, check in this order: seeded data → config table names → NusaOptions cache state → field dependency wiring. In practice the cache and the ->live() wiring account for most reports.