Password Toggle Bundle Laravel Package

Getting Started

• Know what you're installing first. nowo-tech/PasswordToggleBundle is a Symfony bundle, not a Laravel package: it ships a Twig form theme, a CSS file, and a small JS file that adds a show/hide ("eye") toggle to password fields. There is no service provider, no Blade directive, no config/password-toggle.php. Check the package type (symfony-bundle) and the README install snippet before planning anything.
• In a Symfony app: require the package, register the bundle in config/bundles.php, register the form theme in config/packages/twig.yaml (per the README), and include the shipped CSS/JS in your layout. Look first at: the README install block → the bundle's form theme template (as of v2.4.1 this is the authoritative source of the structural classes) → the toggle_container_classes config key.
• First use case: a login form. Add a PasswordType field, render it with the bundle's form theme, and confirm in devtools that the wrapper carries input-group input-group-merge form-password-toggle and that the toggle button flips the input type.
• In a Laravel app: don't install it expecting it to work. Read the template and port the markup, CSS, and JS into a Blade component (<x-password-input>). That's ~30 lines and avoids cross-framework coupling for a very small piece of behavior.

Implementation Patterns

• Let the form theme do the work. Render password fields normally; don't hand-write the input-group wrapper or you'll drift from the shipped CSS/JS contract.
• Additive class customization. toggle_container_classes is merged on top of the template's structural classes (input-group input-group-merge form-password-toggle), with duplicates dropped. Use it for extra classes — margin utilities, design-system hooks — not for structural changes.
• Structural changes go through the template. Override the form theme template if you need different wrapper elements or classes. Config is for additions only.
• Register the form theme globally so login, registration, and password-reset forms all behave identically; per-form registration tends to rot.
• Asset pipeline: wire the shipped CSS/JS through Encore/Vite like any vendor asset. If you compile your own Sass, import the bundle stylesheet instead of copying selectors — the JS depends on those class names.
• Laravel port pattern: a Blade component with the input-group markup, a <button type="button"> toggle carrying aria-pressed, and a one-line JS listener. Keep the class names identical to the bundle's so you can swap back later.
• Test the rendered output once. Assert the container's class list in a feature test; that catches duplicate-class regressions like the one fixed in v2.4.1 without over-specifying markup.

Gotchas and Tips

• What v2.4.1 actually changes: the template is now the authoritative source of the structural classes, and duplicates are dropped. Emptying toggle_container_classes never removed form-password-toggle (it was hardcoded before too) — and it still doesn't. Only a template override changes the structure. The upgrade is otherwise markup-identical minus one redundant class.
• Deduping is silent. If you were relying on a repeated class for a CSS specificity hack, that's gone with no warning.
• The CSS/JS assume the structural classes exist. Stripping form-password-toggle or input-group* in a template override breaks the toggle with no error — just a dead button.
• Brittle test assertions on the exact class string are the only thing likely to fail on upgrade from ≤2.4.0.
• Clear the cache after config or template changes; form theme lookups are cached aggressively and stale templates produce confusing results.
• Debugging: view-source the field first. If the toggle does nothing, check the JS bundle is loaded and that your init selector matches exactly one element.
• Accessibility: the toggle should be a type="button" element with a maintained aria-pressed state. The shipped markup handles this; hand-rolled ports usually forget it.
• Extension points, in order of preference: toggle_container_classes (additive) → template override (structural) → replace the form theme entirely (different DOM contract). There's no event or PHP-level hook worth reaching for on a widget this small.