Filament Lockbox Laravel Package

Getting Started

• Install the alpha explicitly. Being on 1.0.0-alpha.2, pin the exact version ("vendor/filament-lockbox": "1.0.0-alpha.2") rather than a floating constraint — APIs and migrations can still shift between alphas.
• Publish and edit config first. Run php artisan vendor:publish --tag="filament-lockbox-config" and set filament-lockbox.user_model to your application's user class. As of alpha.2 this value is actually honoured (it was hardcoded before), so if you are upgrading from alpha.1 and your auth model is not the default, this is the first thing to fix.
• Set up the three contracts. Your encrypted model implements HasLockbox (and uses InteractsWithLockbox); your user/actor model implements HasLockboxKeys (and uses InteractsWithLockboxKeys). Register the panel/plugin with your Filament panel provider, then run migrations before touching the UI.
• First use case: add a DecryptedTextDisplay column to a Filament table or infolist entry for a field that stores ciphertext. That single swap validates the whole chain — user model resolution, key lookup on the actor, and decryption on the model — and fails loudly (visible warning/error) in each of the common misconfiguration cases, which makes it the fastest smoke test.

Implementation Patterns

• Column/infolist decoration. Use DecryptedTextDisplay wherever you would use TextColumn/TextEntry for encrypted attributes. Its documented behaviours map cleanly onto states you should design for: a decrypted value when the input is present, a warning when input is missing, a dash when the record does not implement HasLockbox, and a dash when the decrypted value is empty. Rely on these rather than duplicating null/contract checks in your resource classes.
• Keep the contracts on the model, not the resource. InteractsWithLockbox handles the record side (encrypt/decrypt accessors), InteractsWithLockboxKeys the actor side (key ownership). Both now share EnsuresModelContext, so context checks are consistent; don't re-implement them in policies or form requests.
• Test with the shipped factories. Lockbox, LockboxUser, and the stub user models plus the newFactory trait let you build realistic fixtures in one line. This is the intended workflow for feature tests around encrypted resources — use LockboxUser::factory() rather than hand-persisting rows, since alpha.2 specifically moved to factories because manual models drifted from the schema (e.g. lockbox_provider).
• Cover the four display branches. Because the component has documented behaviour for missing input, non-HasLockbox records, non-HasLockboxKeys users, and empty values, write one test per branch against your own resource — that's the cheapest way to catch a regression when the next alpha lands.
• Multi-model users. If you have several authenticatable models (admin, customer, API user), lean on the configurable user_model plus the stub user model variations to test each panel context separately.

Gotchas and Tips

• This is pre-release software. 1.0.0-alpha.2 is a bug-fix/feature alpha, not a stability guarantee. Pin the version, read each alpha's changelog before bumping, and avoid depending on internal traits or protected methods.
• Upgrading from alpha.1: the user_model config fix means behaviour changes for anyone whose user model isn't the previous hardcoded default. Clear config cache (php artisan config:clear) after editing and re-verify key lookup — a stale cached config here produces confusing decryption failures.
• Migrations in the test suite. Factories don't create tables. Ensure RefreshDatabase/DatabaseMigrations runs the package migrations, otherwise factory-based tests fail on missing lockbox_provider and similar columns — the exact instability alpha.2 addressed upstream.
• Empty string vs. null is invisible. The dash display collapses "empty" and "missing" decrypted values into one visual. If your UI must distinguish them, don't rely on DecryptedTextDisplay; add a separate placeholder()/formatStateUsing() or a raw ciphertext-presence indicator.
• Contract errors surface in the UI, not the logs. A user model missing HasLockboxKeys renders an error in the component. If you see that in a panel, check the actor's contract and the resolved user_model before debugging encryption itself.
• Static analysis friction. PHPStan previously reported a covariance error on Lockbox::user() (fixed) and flags the internal traits as unused (suppressed in the package's own config). If you extend those traits or override user(), expect to add your own baseline entries and keep your return types covariant.
• Extension points to prefer: the config file, published migrations, and the two public traits/contracts. EnsuresModelContext is an internal DRY helper — treat it as implementation detail, not a stable API surface to build on.