User Password Lost Bundle Laravel Package

Getting Started

1. Update the dependency and let Composer resolve the new floor:

   composer require "vendor/package:^1.0.5" --with-all-dependencies
   

2. Read the diff in composer.json first. This release raises the Symfony and PHP minimums, so confirm your app's PHP version and any Symfony components pinned by Laravel itself (symfony/console, symfony/http-foundation, symfony/process, etc.) still satisfy the new constraints:

   composer why-not vendor/package 1.0.5
   php -v
   

3. Clear compiled artefacts before exercising anything, since service definitions and autowiring changed:

   php artisan cache:clear
   php artisan config:clear
   composer dump-autoload -o
   

4. First use case to verify: password hashing. The package now expects UserPasswordHasherInterface, so a smoke test through your login and password-reset flows is the fastest way to confirm the container wires the new service correctly:

   use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
   
   public function __construct(private UserPasswordHasherInterface $hasher) {}
   
   public function hash(string $plain): string
   {
       return $this->hasher->hashPassword($this->user, $plain);
   }
   

5. Second smoke test: repository resolution. Confirm any code fetching a repository via a raw string now uses the class constant, otherwise you will get a "repository not found" style failure at runtime rather than at compile time.

Implementation Patterns

Inject the hasher, don't construct it. The interface is autowired by the framework. Type-hint UserPasswordHasherInterface in constructors, actions, and form handlers. Avoid reaching into the container.

Wrap hashing behind your own contract. Laravel developers usually want an app-level boundary so the framework detail does not leak into domain code:

interface PasswordHasher
{
    public function hash(object $user, string $plain): string;
    public function verify(object $user, string $plain): bool;
}

final class FrameworkPasswordHasher implements PasswordHasher
{
    public function __construct(private UserPasswordHasherInterface $hasher) {}

    public function hash(object $user, string $plain): string
    {
        return $this->hasher->hashPassword($user, $plain);
    }

    public function verify(object $user, string $plain): bool
    {
        return $this->hasher->isPasswordValid($user, $plain);
    }
}

Bind it in a service provider and your tests can swap in a fake — this also isolates you from the next rename.

Use class constants for repository lookup. Wherever the package or your integration code calls getRepository(), pass PasswordResetRequest::class rather than a hand-written string. The same applies in config and in doctrine.yaml mappings. This turns typos and namespace moves into static-analysis errors.

$repository = $entityManager->getRepository(PasswordResetRequest::class);

Migrate encoder call sites mechanically. Search the codebase for the old API and replace method names and types together — the interface rename and the method rename shipped as a pair, so half-migrated code will type-error:

grep -rn "UserPasswordEncoderInterface\|encodePassword" app/ src/ config/

Run both flows in CI. Add a feature test that registers a user, authenticates, requests a reset, and completes it. Those four steps touch every changed surface in this release, and they are cheap to run on every push.

Pin deliberately during rollout. If you cannot upgrade the whole stack at once, pin the previous minor for the affected service while you migrate, but keep the hasher migration in the same PR — splitting them leaves the container in a state where neither interface is reliably resolvable.

Gotchas and Tips

This is a breaking release disguised as a patch. The encoder-to-hasher rename is not backwards compatible: UserPasswordEncoderInterface and encodePassword() are gone, not deprecated. Any third-party bundle or internal package still type-hinting the old interface will fail container compilation, and the error surfaces as a Cannot autowire service message that names your class, not the offending dependency. Use bin/console debug:container "UserPasswordHasherInterface" (or the Laravel equivalent) to confirm exactly one implementation is registered.

Method signatures changed alongside the name. isPasswordValid() on the hasher takes the user as its first argument, matching the hash side. Copying an old call site and renaming only the method will pass the wrong argument order without a type error in loosely typed code.

Composer resolution fights Laravel's own pins. Laravel ships Symfony components at its own versions. The raised floor here can produce a conflict that composer update reports against a package you never installed directly. Resolve with composer why-not on the specific component, and prefer bumping Laravel before forcing an --ignore-platform-reqs workaround — the latter defers a runtime failure into production.

Clear the compiled container after every change to service definitions. Autowiring errors and stale repository aliases both hide behind a cached container. If behaviour does not match the code, clear first and re-test before debugging deeper.

Repository alias mismatch is a silent failure mode. A string-based lookup that no longer matches a service alias will throw at the point of use, often inside a listener where the stack trace is unhelpful. Grep for getRepository(' and getRepository(" and convert all of them in one pass.

Debugging tip: log the resolved hasher class at boot in non-production. One line in a service provider confirms which implementation answered autowiring, which distinguishes "wrong service registered" from "right service, wrong config" in a single deploy.

Extension points worth knowing. Custom hashing behaviour is configured through the package's password hasher settings rather than by replacing the service — substituting your own implementation of the interface will be overwritten during container compilation unless you explicitly decorate it. Use decoration (or the documented config key) so the change survives upgrades, and keep a test asserting the custom algorithm is actually in use.

Version-check your test matrix. The raised PHP and Symfony floors mean CI images that were fine last week may now resolve a different dependency graph. Pin the PHP version in CI to match production and add a job at the new minimum so the floor is genuinely tested rather than assumed.