Make "status" session values more consistent and easily translatable

[alexandercrice]

Complaint

Currently Fortify flashes text values like "two-factor-authentication-enabled" to the session under the key "status". The Fortify documentation page suggests handling these status values, by checking for these values with an if-statement, and then displaying a suitable message.

https://laravel.com/docs/8.x/fortify#enabling-two-factor-authentication

It would be nice if it were easier to convert the original value to a human-friendly message using the trans() (translate) function. That way, if the message is displayed using some kind of general/global component, it can simply display the translated value rather than having to implement some kind of case statement.

Fortify is also inconsistent about the kind of status value used. In places where Fortify makes use of statuses returned from the Laravel Framework (which are formatted in an easily translatable dotted format, e.g., "passwords.throttled"), Fortify calls trans() on these values before saving them to the session. However, in places where Fortify implements it's own status values, it uses hyphenated strings, like "two-factor-authentication-enabled" and does not call trans() on them. Why this inconsistency? If Fortify translates the Laravel Framework's status values, Fortify should translate its own status values too.

Since Fortify's current status values are not dotted, it is also more difficult to translate them than if they were dotted. My understanding is that unless the value-to-be-translated contains a dot, it is necessary to translate them with a ".json" file, taking away the option of using PHP translation files. In order to use PHP translation files, there needs to be (at least) two segments separated by a dot, with the first segment giving the PHP translation file to use. E.g., the string value "fortify.two-factor-authentication-enabled" indicates to the trans() function that it should return the value at the array key "two-factor-authentication-enabled" in the array returned by the fortify.php translation file. If one prefers JSON translation files, the option still remains to define a translation in a JSON file at the key "fortify.two-factor-authentication-enabled".

Example

Compare how Fortify handles the status message in the Laravel\Fortify\Http\Controllers\TwoFactorAuthenticationController::store method

versus how the status message is handled in Laravel\Fortify\Http\Responses\PasswordResetResponse.

For examples of the dotted format, see the Laravel Framework's Illuminate\Contracts\Auth\PasswordBroker interface.

Which are handled in a passwords.php translation file.

Proposed Solution

Simply replacing the status values that Fortify uses with new values would break existing applications.

Instead, the change could be implemented in a non-breaking way by adding an (optionally present) variable in the fortify.php configuration file. By default, Fortify would continue to use the same status values as the current ones. However, changing this new configuration variable would cause Fortify to use different status values, following the pattern set by the Laravel Framework.

Then the places in the code could be updated to return one of two different values, depending on the value of this configuration variable. So, for example,

return $request->wantsJson()
                    ? new JsonResponse('', 200)
                    : back()->with('status', 'two-factor-authentication-enabled');

could become

return $request->wantsJson()
                    ? new JsonResponse('', 200)
                    : back()->with('status', config('fortify.use-more-easily-translatable-status-values', false) ? 'two-factor-authentication-enabled' : 'fortify.two-factor-authentication-enabled');

And, as stated above, Fortify should apply the trans() function for sake of consistency.

return $request->wantsJson()
                    ? new JsonResponse('', 200)
                    : back()->with('status', trans(config('fortify.use-more-easily-translatable-status-values', false) ? 'two-factor-authentication-enabled' : 'fortify.two-factor-authentication-enabled'));

It would would also be beneficial for Fortify to provide its own translation file. Besides serving as a model for consumers of the Fortify package who would like to define their own translations, it would also serve as documentation of Fortify's status values. Currently there is no good reference that lists these values together in one place. One must read through the Fortify page on the Laravel website to find the value used on a feature-by-feature basis, or open the source code to find the response and controller classes for a particular feature.

The translation file could even just map the value to itself.

return [
    'two-factor-authentication-enabled' => 'two-factor-authentication-enabled',
    // ...
];

[driesvints]

The idea was probably to totally leave it up to the implementer to translate these strings. With that in mind, I think the concept of setting the status to determine the "type" of error and leaving it to the implementer to choose which kind of message to render makes sense. We could ship a language file like you suggest but tbh we could simple also just leave that to the implementing app/package.

I'll leave it to Taylor to decide on this.

[taylorotwell]

You can call the __ translation helper from your template with any string you want.

[alexandercrice]

@taylorotwell

You can call the __ translation helper from your template with any string you want.

The problem is not that it can't be translated, but (1) that it it's more difficult than it should be, and (2) that Fortify is inconsistent with the nature of these "status" messages. In some cases they are human-friendly status messages, and in other cases they are human-unfriendly status codes. But these very different kinds of values are both stored in the session under the same key.

Another related problem (straying a bit from the immediate point) is that it it is difficult to override the default Fortify's behavior in many cases, and this is due in part to the inconsistent nature of how Fortify's features are implemented. For some features, redirect behavior (for example) can be customized from the config file, but in other cases not. In some cases, a response contract binding can be overridden or extended, but in other cases, there is no response contract and the response is created directly in the controller, requiring (I think) the user to override the route definition in their own project's route file, or else resort to more creative solutions.

---

When a user successfully resets their password, Fortify takes the string Password::PASSWORD_RESET (value: "passwords.reset"), translates it (which is handled by a translation file resources/lang/(locale)/passwords.php, from the stock laravel/laravel project template), and flashes that translated value to the string. A user of Fortify can display this status message (which will already be a human-friendly value, like "Your password has been reset!") on a page without any special treatment.

On certain other responses (those not making use of string constants defined in laravel/framework), Fortify flashes an untranslated, non-humanfriendly string to "status". The suggestion from the documentation page is that we should check for the "status" value in the template for that particular page and then print out some different message (which can indeed be translated with __()). Using the example from Enabling Two Factor Authentication:

I take your comment as saying that we can do the following:

@if (session('status') == 'two-factor-authentication-enabled')
    <div class="mb-4 font-medium text-sm text-green-600">
        {{ __('Two factor authentication has been enabled.') }}
    </div>
@endif

But that misses the point of this complaint.

First, is that it's inconsistent. All these Fortify features are using the "status" session key, but for two very different kinds of values: status messages and status codes. This makes Fortify unnecessarily cumbersome to use because it is not following a consistent convention or pattern. It also prevents us from using a general component that can handle these kinds of messages on multiple pages. Instead of having a component along these lines

@isset(session('status'))
<div class="success-banner">
    {{ __(session('status')) }}
</div>
@endisset

we are encouraged to write a template like

@isset(session('status'))
<div class="success-banner">
@switch(session('status'))
    @case('two-factor-authentication-enabled')
        {{  __('Two factor authentication has been enabled.') }}
        @break
    @case('two-factor-authentication-disabled')
        {{ __('Two factor authentication has been disabled.') }}
        @break
    {{-- and so on, and so on --}}
    @default
        {{-- Maybe include a default case, to handle routes like PASSWORD_RESET. --}}
        {{-- But since Fortify has already "translated" them, you don't need to invoke that function here, --}}
        {{-- although it probably wouldn't hurt if you did.  --}}
        {{ session('status') }}
    @endswitch
</div>
@endisset

Or else, effectively the same thing as the above, but broke out into separate templates for each individual page. Either way, we are being asked (if we follow the guidance on the documentation page) to translate a key to a human-friendly message in the Blade template. But translating string keys to intelligible messages is the role of the translation file, not the Blade template.

A second problem is that if you want to translate the string (e.g. "two-factor-authentication-enabled") directly (__(session('status'))), you are forced to use a JSON translation file rather than a PHP translation file because there is no dot in the string. This is a more minor point, but there are reasons to prefer PHP translation files over JSON, e.g., because JSON files don't allow comments. For the laravel/framework status values, the string is always dotted, e.g. "passwords.reset". It would be easy for Fortify to follow this pattern and allow PHP translation files by just adding a prefix of some kind, like "fortify.two-factor-authentication-enabled" or "two-factor-authentication.enabled".

This is not an unsolvable problem from the consumer's end, but I found it to be enough of inconvenience while updating a project from Laravel UI to using Fortify to merit the time spent submitting this issue.