Correos

Una vez creada una cuenta (por defecto no verificada), se le envía con un correo al email que se usó para registrarse con un código que debe utilizar por medio de un enlace, luego de abrir el link la cuenta es verificada.

1. Preparación del sistema para el envío de correos electrónicos

• Descargar paquete

composer require guzzlehttp/guzzle

• Seleccionar servicio de correo en archivo config/services.php

Se selecciona el servicio a utilizar para ello se deben añadir las variables de entorno al archivo .env y configurar los campos según los valores de las cuentas que se hayan creado en dichos servicios.

Por ejemplo en caso de usar mailgun se tiene:

MAILGUN_DOMAIN=
MAILGUN_SECRET=

• Configurar servicio de correo en archivo config/mail.php

Driver

Según el servicio seleccionado, se debe especificar el mail driver (por ejemplo, colocar mailgun), y variables relacionadas con el mismo.

En este caso se utilizará el archivo de log para facilitar la depuración:

MAIL_DRIVER=log
# MAIL_HOST=smtp.mailtrap.io
# MAIL_PORT=2525
# MAIL_USERNAME=null
# MAIL_PASSWORD=null
# MAIL_ENCRYPTION=null

Configuración del remitente global --> Global "From" Address

Es la cuenta de correo que usará Laravel cada que envíe un mensaje.

Es recomendado utilizar en el MAIL_FROM_ADDRESS el mismo dominio del servicio de correo (mailgun, sparkpost), en este caso se utilizará el dominio local (@localhost) y como nombre el valor que se prefiera

MAIL_FROM_ADDRESS=postmaster@localhost
MAIL_FROM_NAME="API RESTful"

Nota: los cambios realizados al .env deben agregarse al archivo .env.example

2. Implementar sistema de verificación

• Crear ruta en routes/api.php

Route::name('verify')->get('users/verify/{token}', 'User\UserController@verify');

• Crear método verify en User/UserController.php

public function verify($token)
{
    $user = User::where('verification_token', $token)->firstOrFail();

    $user->verified = User::VERIFIED_USER;

    // After verifying remove token (unnecessary)
    $user->verification_token = null;

    $user->save();

    return $this->showMessage('The account was successfully verified');
}

3. Mailable para verificar usuarios creados

• Crear Mailable usando php artisan

Un mailable es una clase que permite especificar los aspectos relacionados con el envío de correos electrónicos, como destinatario, tema, contenido, vista, etc...

php artisan make:mail UserCreated

Nota: los mailables (UserCreated) se guardan dentro de la carpeta app/Mail

• Personalizar Mailable

use App\User;

class UserCreated extends Mailable
{
    use Queueable, SerializesModels;

    // Crear atributo publico para el usuario
    public $user;

    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct(User $user)
    {
        // Esto directamente inyecta el usuario en la vista que retorna el build()
        $this->user = $user;
    }

    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->text('emails.welcome')
            ->subject('Please confirm your email');
    }
}

Notas:

*Cualquier propiedad public definida en el mailable estará disponible en la vista

*En el método build, se puede retornar una versión en texto plano del correo usando el métodotext.Al igual que el método view, el métodotextacepta el nombre del template name que será usando para mostrar el contenido del email. Se pueden definir ambos simultáneamente

• Crear vista que retornará el Mailable

Crear carpeta para guardar las vistas en views/emails. En este caso crear welcome.blade.php y personalizar mensaje que mostrará

Hi {{ $user->name }}

Thanks for creating an account. Please verify it using this link:

{{ route('verify', $user->verification_token) }}

• Enviar correo de verificación usando evento del modelo User

En app/Providers/AppServiceProvider.php en el método boot()

use App\User;
use App\Mail\UserCreated;
use Illuminate\Support\Facades\Mail;

// Send Message to verify account
User::created(function($user) {
    // Is not required to specify user email, Laravel obtains it from the user model
    Mail::to($user)->send(new UserCreated($user));
});

• Verificar funcionalidad con Postman

Crear un usuario

Teniendo en cuenta que el driver que estamos utilizando es log, cada que se envie un mail, este se registrará en el archivo de log de laravel, este se encuentra en storage/logs/laravel.log

Para verificar la cuenta, simular que el usuario abrió el link haciendo una petición get

Y finalmente, se tiene que la cuenta fue verificada

4. Vistas especialmente para correo electrónico --> Markdown

Permite utilizar etiquetas predefinidas en blade para facilitar la creación de interfaces para correos todas en html (tablas, títulos, ...).

Para crear un Mailable con un Markdown llamado prueba (en la carpeta views/emails) asociado

php artisan make:mail Prueba -m emails.prueba

De esta manera se generan 2 archivos: la clase /app/Mail/Prueba.php

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Contracts\Queue\ShouldQueue;

class Prueba extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->markdown('emails.prueba');
    }
}

y la vista /resources/views/emails/prueba.blade.php

Así, se tiene un template con una estructura

@component('mail::message')
# Introduction

The body of your message.

@component('mail::button', ['url' => ''])
Button Text
@endcomponent

Thanks,<br>
{{ config('app.name') }}
@endcomponent

• Configurar templates usando etiquetas Markdown

Ahora, utilizando la estructura del Markdown, se procede a modificar la estructura de los templates de views/emails (en una próxima ocasión crear el Mailable con el Markdown directamente).

@component('mail::message')
# Hi {{ $user->name }}

Thanks for creating an account. Please verify it using this button:

@component('mail::button', ['url' => {{ route('verify', $user->verification_token) }} ])
Verify my account
@endcomponent

Thanks,<br>
{{ config('app.name') }}
@endcomponent

• Modificar Mailable de UserCreated

En el método build especificar que se retornará un markdown, no text.

public function build()
{
    return $this->markdown('emails.welcome')
        ->subject('Please confirm your email');
}

• Verificar funcionalidad con Postman

Dentro del log se registra el código HTML generado con el Markdown

5. Mailable para validar un nuevo correo

En caso de que los usuarios cambien su correo electrónico

• Crear Mailable

php artisan make:mail UserMailChanged -m confirm

• Personalizar Mailable

use App\User;

class UserMailChanged extends Mailable
{
    use Queueable, SerializesModels;

    public $user;

    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct(User $user)
    {
        $this->user = $user;
    }

    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->markdown('emails.confirm')
            ->subject('Please confirm your new email');
    }
}

• Crear vista que retornará el Mailable

Crear carpeta para guardar las vistas en views/emails. En este caso crear welcome.blade.php y personalizar mensaje que mostrará

@component('mail::message')
# Hi {{ $user->name }}

You have changed your email. Please verify it using this button:

@component('mail::button', ['url' => {{ route('verify', $user->verification_token) }} ])
Verify my account
@endcomponent

Thanks,<br>
{{ config('app.name') }}
@endcomponent

• Enviar correo de verificación

En app/Providers/AppServiceProvider.php en el método boot()

use App\User;
use App\Mail\UserMailChanged;
use Illuminate\Support\Facades\Mail;

// Send Message to verify new email
User::updated(function($user) {
    // Verify if mail has changed
    if($user->isDirty('email'))
    {
        Mail::to($user)->send(new UserMailChanged($user));
    }
});

6. Reenviar correo de verificación

Esto con la finalidad de que el usuario pueda pedir le sea reenviado el correo de verificación en caso de no recibirlo, o si hubo algún problema y el correo no fue enviado

• Crear ruta en routes/api.php

Route::name('resent')->get('users/{user}/resend', 'User\UserController@resend');

• Crear método verify en User/UserController.php

use App\Mail\UserCreated;
use Illuminate\Support\Facades\Mail;

public function resend(User $user)
{
    if($user->isVerified())
    {
        return $this->showMessage('The account has been verified', 409);
    }

    Mail::to($user)->send(new UserCreated($user));

    return $this->showMessage('Validation email has been resend', 409);
}

• Verificar funcionalidad con Postman

7. Manejar acciones propensas a errores

Lidiar con acciones que pueden ser propensas a fallas, por ejemplo el envío de correos, para esto se usará el helper. Este helper permite reintentar una misma acción en diferentes ocasiones en caso de haber fallado, con un máximo de intentos.

• Añadir helper en los lugares en que se envíen correos (AppServiceProvider.php y UserController)

// retry (times, function to execute, time (miliseconds) between tries)
retry(5, function() use($user) {
    Mail::to($user)->send(new UserMailChanged($user));
}, 100);

Nota: si la función falla, Laravel reintentará ejecutarla el número de veces fijadas en el retry. En caso de completar el número de intentos y no conseguir ejecutar la función será lanzada una excepción