Pathwell Bundle Laravel Package

Getting Started

This is a thin Symfony bundle (single release, June 2022) that wraps a PathWell topology check: it maps each character of a password to a class (lower, upper, digit, symbol), builds a topology string like ULLLLLDD, and rejects passwords whose topology is in a configured list of common/weak topologies. It is a policy validator, not an entropy or breach checker.

1. Check the licence before anything else. GPL-3.0 is a copyleft licence; for a closed-source product this usually needs legal sign-off or an alternative implementation. Confirm this before you invest in integration.
2. Install and register:

   composer require guilhermednt/pathwell-bundle
   

   If Flex has no recipe, add it manually to config/bundles.php (Guilhermednt\PathWellBundle\PathWellBundle::class => ['all' => true], verify the exact namespace in vendor/.../src/).
3. Look first at three places in the vendor directory: src/DependencyInjection/Configuration.php (the real config tree — the README is sparse), src/Validator/ (the constraint + validator pair you'll actually use), and src/Resources/config/ (service tags, especially validator.constraint_validator).
4. Write a minimal config/packages/pathwell.yaml enabling the check and pointing at a topology list. The list is the policy — a bundle with an empty or default list does nothing useful, so budget time for sourcing data (see below).
5. First use case: the registration form. Put the constraint on the transient plainPassword field, never on the entity's hashed password property:

   ->add('plainPassword', RepeatedType::class, [
       'type' => PasswordType::class,
       'constraints' => [
           new Length(['min' => 12]),
           new PathWell(),            // FQCN from src/Validator/
           new NotCompromisedPassword(),
       ],
   ])
   

6. Verify wiring with bin/console debug:validator App\Entity\User (or your DTO) and bin/console lint:container; a silently unregistered validator tag means every password passes.

Implementation Patterns

Apply it at the boundary, not on the entity. Passwords arrive as plaintext on forms, API payloads, and console commands; they leave as hashes. Use a DTO (RegistrationInput, ChangePasswordInput) or form-level constraints so the rule is reusable across web, API, and admin paths without fighting Doctrine lifecycle callbacks.

Cover all three entry points consistently: self-registration, password change, and password reset. A policy enforced only on registration is trivially bypassed via "change password". Admin "invite/create user" flows are the usual hole.

Compose, don't substitute. PathWell rejects predictable shapes (Password1! passes a length check but fails topology). Pair it with Length/PasswordStrength and NotCompromisedPassword. Order matters: cheap checks first so users get the most actionable error.

Treat the topology list as configuration with a lifecycle. Source it from the published PathWell topology corpus or generate it from your own password corpus; store it as a versioned file in config/ and load it via the bundle's config key rather than inlining thousands of entries into YAML. Review it periodically — the ranked list drifts as attacker dictionaries evolve.

Per-environment tuning: strict in prod, and either strict-but-fixed or disabled in test so fixture passwords stay deterministic. Don't disable it in dev if you want developers to hit the same UX you ship.

Legacy users: apply the policy on change, not on login; never lock out existing accounts because their old hash can't be re-validated.

Custom error messaging. Topology rejections are confusing ("your password pattern is too common"). Override the constraint's message and provide a translation, or users will assume the form is broken. Point them at the fix: "use a less predictable mix of words, numbers, and symbols."

Test at two levels. A unit test building the validator via Validation::createValidatorBuilder()->enableAnnotationMapping()-style bootstrap for the constraint itself, plus one functional form test asserting a known-bad topology (Password1) fails and a good one passes. This also catches upstream breakage on Symfony upgrades.

Gotchas and Tips

• Zero stars, one release, GPL-3.0. Audit the source (it's small — a few hundred lines at most) and pin the exact version in composer.json. For many teams the honest conclusion is "reimplement the 50-line topology check in-house" — it's a character-class map plus a hash-set lookup, and you avoid the licence and abandonment risk entirely.
• Symfony compatibility. A 2022 bundle may cap symfony/framework-bundle below 6.4/7.x and may emit deprecations on PHP 8.2+. Run composer why-not symfony/framework-bundle ^7.0 and a full test suite before adopting; forks are likely.
• Empty or missing topology list = no protection. This is the number-one silent failure. Assert at boot (or in a test) that the configured list is non-empty.
• It measures shape, not strength. aaaaaaaaaaaa and qwertyuiop12 can survive a topology check. Always combine with length and a breach list.
• Character-class edge cases. Decide and document how you classify _, whitespace, and non-ASCII letters; use multibyte-safe splitting (mb_str_split) so accented characters don't corrupt the topology string. Uppercase detection for non-Latin scripts is unreliable — consider treating them as a single class.
• Don't load a huge list into container parameters if it's tens of thousands of entries; it bloats the compiled container and cache:clear time. Load it in a service from a resource file, cached in memory per request.
• Debugging: bin/console debug:container --tag=validator.constraint_validator confirms registration; debug:validator shows constraints per class. If validations appear to be ignored, it is almost always a missing service tag or a constraint applied to the wrong property.
• Extension points: decorate the topology-checker service to add logging/metrics (top rejection reasons are genuinely useful product data), and override the constraint message via translations rather than forking.
• Don't let the constraint's existence imply compliance. If your security requirements cite NIST SP 800-63B, topology filtering is a supplementary control; length + breach screening are the primary ones.