Nova Password Toolkit Laravel Package

Getting Started

• Check the constraints before anything else. PHP 8.2+, Laravel 11/12, Nova 5, and gabrielesbaiz/password-toolkit 2.0+ are all hard requirements. If the host app is still on Nova 4 or Laravel 10, stop here — there is no fallback path.
• Install with the beta constraint and pin it. composer require gabrielesbaiz/nova-password-toolkit:^1.0@beta will happily float you across pre-releases while the API is described as "settling". Commit composer.lock immediately, and consider tightening to an exact 1.0.0-beta.1 in composer.json for anything customer-facing. Remember the @beta stability flag applies to this package's own constraint, not transitive ones.
• Look first at three things: the published config file (dictionary and generation options that back the dashboard), the service provider that registers the Field macros, and the registered routes — the release notes stress that route names and endpoints are unchanged from the originating application, so php artisan route:list is the fastest map of the surface area.
• First use case: add ->withPasswordSuggestion() to the password field on your user/resource form in Nova, and optionally chain ->withPasswordStrengthMeter(). That single change is the whole value proposition — you get a generator, a dictionary-aware suggestion, and a strength meter without writing front-end code.
• Then run the sync command once (php artisan password-toolkit:sync-types) to make sure your config carries every key this version expects, and open the settings dashboard to confirm it renders and saves.

Implementation Patterns

Settings dashboard as the single source of truth. Treat the dashboard (dictionary picker, generation options, the toolbar that persists both) as the place operators tune policy, and avoid hardcoding those values in your own config or form defaults. If the dashboard should be restricted, wire it to the managing authorization check rather than an ad-hoc gate — see below.

Compose the macros, don't fork the field. Field::withPasswordSuggestion() and Field::withPasswordStrengthMeter() are independent, so you can ship suggestion-only on a low-risk form (a service account credential, say) and both on user-facing registration. Use the passwordSuggestionHelp() global for the help text so the copy stays consistent with whatever the package renders.

Understand the asymmetric authorization before you rely on it. The two checks are deliberately opposite:

• Managing (the dashboard, saving options) fails closed — a missing or misconfigured gate denies access. That is the safe default; it means a botched policy setup breaks the settings screen loudly rather than silently.
• Suggesting fails open — a misconfigured check still permits suggestions. Convenient, but it means "the strength meter is visible" is not evidence that authorization is configured correctly.

In practice: define both abilities explicitly in a policy or gate, and write a test asserting the managing ability denies for a non-admin. Relying on the fail-open default for suggesting means you will never notice if the check is broken.

Put the sync command in the deploy pipeline. password-toolkit:sync-types is additive-only — it adds newly-released config keys and leaves existing values alone — which makes it safe to run on every deploy after composer install. That is exactly the right shape for a package that ships new options: without it, an upgrade silently leaves your config missing keys the dashboard expects.

Pluggable config-path resolution for multi-brand/multi-tenant apps. This is the feature that makes the package viable outside a single-tenant app. Bind the resolver so each tenant/brand resolves its own config file, and resolve it at request time, not at container-boot time. Test explicitly with php artisan config:cache in play — path resolution that works in local and breaks under cached config is the classic failure mode here.

Translations come for free but verify the bridge. English and Italian are bridged into Nova's own front-end catalogue, so there is nothing to publish for the common case. If you have added locales, confirm the fallback behaviour on the dashboard and on field help text rather than assuming.

Lean on the provenance. This was extracted from a running application with markup, endpoints, and route names preserved. That means the extraction is low-risk, but it also means the shape is legacy — expect Nova conventions rather than a freshly designed API, and expect the route names to reflect the original app's naming.

Gotchas and Tips

• Beta means the API is explicitly unsettled. The maintainer says so in the release notes. Avoid depending on the macro signatures, config keys, or route names from a shared internal package of your own without pinning; a ^1.0 constraint against a beta line is a moving target.
• sync-types never removes or renames. If upstream renames a config key between betas, the old entry lingers and you can end up with two keys that appear to do the same thing. Diff the published config against yours after each upgrade instead of trusting the command alone.
• Fail-open suggesting is a real exposure decision, not a detail. If you were planning to hide the strength meter or suggestions from a class of users, this package will not do that for you by default. Audit the gate deliberately.
• Config-path resolution vs. config:cache. Re-test after enabling cached config in staging. If the dashboard shows the wrong brand's dictionary, this is the first place to look.
• Macros are global state. Register them once, in a single service provider. If two packages (or a leftover snippet from the original extraction) register withPasswordSuggestion, you get a confusing last-one-wins behaviour with no error.
• Route name collisions. Because names were preserved verbatim from the source application, an app that previously copy-pasted those cards/routes into its own routes/ will now have duplicates. Grep for the route names before installing.
• Translations may need a front-end rebuild. If Italian strings do not appear after switching locale, check whether Nova's compiled assets need republishing or a hard refresh before assuming the bridge is broken.
• Keep password-toolkit in lockstep. The 2.0+ floor is a floor, not a ceiling; upgrade the underlying toolkit and this package together and re-run the sync command.
• Debugging order when something looks wrong: (1) did the sync command run post-deploy, (2) which config path did the resolver return, (3) does the managing ability resolve for this user, (4) are the macros actually registered. Those four cover most of the surface.