[12.x] Types: Password::reset

[liamduckett]

Hey, following on from #55109 - this PR implements the same change for the interface, and facade.

[donnysim]

I don't think this change to interface is correct, the string type is correct from the frameworks perspective, but not from 3rd party implementing them - they do not have to conform to the string type and the return value is not being used by the framework.

[liamduckett]

I don't think this change to interface is correct, the string type is correct from the frameworks perspective, but not from 3rd party implementing them - they do not have to conform to the string type and the return value is not being used by the framework.

@donnysim I think this is a fair criticism. I did consider this when implementing - apologies, I should have definitely written it up in the PR description.

I think the current mixed return type is too wide, requiring consumers to handle entirely unrealistic scenarios just to be type-safe. Consider the following example (roughly taken from Laravel Breeze):

$status = Password::reset(
    $validated,
    function (User $user) use ($validated) {
        $user->forceFill([
            'password' => Hash::make($validated['password']),
            'remember_token' => Str::random(60),
        ])->save();

        event(new PasswordReset($user));
    }
);

// If the password was successfully reset, we will redirect the user back to
// the application's home authenticated view. If there is an error we can
// redirect them back to where they came from with their error message.
return $status === Password::PASSWORD_RESET
            ? redirect()->route('login')->with('status', __($status))
            : back()->withInput($request->only('email'))
                ->withErrors(['email' => __($status)]);

Reports:

 ------ -------------------------------------------------------------------- 
  Line   app/Http/Controllers/Auth/NewPasswordController.php                 
 ------ -------------------------------------------------------------------- 
  61     Parameter #1 $key of function __ expects string|null, mixed given.  
         🪪  argument.type                                                   
 ------ --------------------------------------------------------------------

For anyone who hasn't implemented their own PasswordBroker (I'd hazard a guess that this is more than 99% of users) this is an unnecessary complaint - as $status will always be a string. Extra code to handle this "potential" mixed feels wasteful to me.

Additionally, I see (interested to see if people agree) these interfaces as a way for users to ensure their code "behaves" in line with Laravel's own implementations - I think (whilst technically a very minor breaking change) that narrowing this type helps users do that, likely simplifying their own code in the process.

(For once) I think the usage of PHPDocs aids this change here, as the "breaking change" is actually completely disregarded at runtime.

[donnysim]

I understand where you're coming from, but at the same time these components are used outside of Laravel too. Majority of cases involve application code where there is nothing to handle by the framework or a library such as breeze, as the auth code is also custom, I don't see anyone extending these without application code to handle new cases, such as external service password resets etc. that return a more detailed response rather than just a measly string.