[5.7] Mailables can hook into LocaleUpdated

[derekmd]

This makes send() of translated Mailable (and eventually Notification) objects dispatch the event Illuminate\Foundation\Events\LocaleUpdated to allow for more complete localization. For example:

• Carbon-formatted timestamps
• Currency and money output
• route() country/region URI prefixes

Translatable mailable classes were added in 5.6.5 (#23178) to allow translated email subjects and view bodies, but the above localizable content types are left unchanged for queued items.

Example to localize mailable timestamps

When the default queue worker locale is 'en', calling Mail::to($francophone)->locale('fr')->queue(new Schedule); would show French formatting for Carbon timestamps using this event listener.

\Illuminate\Foundation\Events\LocaleUpdated::class => [
    \App\Listeners\LocalizeApp::class,
],

namespace App\Listeners;

use Illuminate\Support\Carbon;
use Illuminate\Foundation\Events\LocaleUpdated;

class LocalizeApp
{
    public function handle(LocaleUpdated $event)
    {
        // Carbon@formatLocalized() / strftime()
        setlocale(LC_TIME, array_get([
            'en' => 'en_CA.UTF-8',
            'fr' => 'fr_CA.UTF-8',
        ], $event->locale, 'en'));

        // Carbon@diffForHumans()
        Carbon::setLocale($event->locale);
    }
}

Flexibility in implementation

I chose the simplest solution (1. below) but this pull request to can be changed one of the following (or another approach entirely.)

1. Simplest: Assume by localizing a mailable, the app container instance has getLocale() / setLocale() methods.

   public function withLocale($locale, $callback)
   {
       if (! $locale) {
           return $callback();
       }
   
       $app = Container::getInstance();
   
       // throws exception for custom containers
       // maybe you shouldn't be trying to locale() a mailable
       $original = $app->getLocale();

2. Hack: Check explicitly for Laravel's concrete Application container.

   public function withLocale($locale, $callback)
   {
       $app = Container::getInstance();
   
       if (! $locale || ! $app instanceof \Illuminate\Foundation\Application) {
           return $callback();
       }
   
       $original = $app->getLocale();

3. Custom Container-friendly Contract: Make Laravel's app container implement a new interface.

   interface LocalizedApplication
   {
       public function setLocale($locale);
       public function getLocale();
       public function isLocale($locale);
   }

   class Application
       extends Container
       implements ApplicationContract, HttpKernelInterface, LocalizedApplication
   {

   public function withLocale($locale, $callback)
   {
       $app = Container::getInstance();
   
       if (! $locale || ! $app instanceof LocalizedApplication) {
           return $callback();
       }
   
       $original = $app->getLocale();

This changes the method signature of Illuminate\Support\Traits\Localizable@withLocale() so this pull request is proposed for 5.7.