Spanish (Español) translation by Rafael Chavarría (you can also view the original English article)
En este artículo, vamos a explorar la API Mail en el marco de trabajo web Laravel. Laravel saca ventaja de la popular librería SwiftMailer, la cuál es sencilla de usar y viene con una variedad de controladores de email de los cuáles elegir. En las etapas posteriores del artículo, iremos en una demostración a profundidad de los conceptos discutidos en la primera mitad del artículo.
Configurando los Prerequisitos.
Laravel implementa un envoltorio encima de la librería SwiftMailer que hace la administración de email muy sencilla de configurar y usar al mismo tiempo. Puedes encontrar los ajustes de correo por defecto en config/mail.php.
1 |
<?php
|
2 |
|
3 |
return [ |
4 |
|
5 |
/*
|
6 |
|--------------------------------------------------------------------------
|
7 |
| Mail Driver
|
8 |
|--------------------------------------------------------------------------
|
9 |
|
|
10 |
| Laravel supports both SMTP and PHP's "mail" function as drivers for the
|
11 |
| sending of e-mail. You may specify which one you're using throughout
|
12 |
| your application here. By default, Laravel is setup for SMTP mail.
|
13 |
|
|
14 |
| Supported: "smtp", "sendmail", "mailgun", "mandrill", "ses",
|
15 |
| "sparkpost", "log", "array"
|
16 |
|
|
17 |
*/
|
18 |
|
19 |
'driver' => env('MAIL_DRIVER', 'sendmail'), |
20 |
|
21 |
/*
|
22 |
|--------------------------------------------------------------------------
|
23 |
| SMTP Host Address
|
24 |
|--------------------------------------------------------------------------
|
25 |
|
|
26 |
| Here you may provide the host address of the SMTP server used by your
|
27 |
| applications. A default option is provided that is compatible with
|
28 |
| the Mailgun mail service which will provide reliable deliveries.
|
29 |
|
|
30 |
*/
|
31 |
|
32 |
'host' => env('MAIL_HOST', 'smtp.mailgun.org'), |
33 |
|
34 |
/*
|
35 |
|--------------------------------------------------------------------------
|
36 |
| SMTP Host Port
|
37 |
|--------------------------------------------------------------------------
|
38 |
|
|
39 |
| This is the SMTP port used by your application to deliver e-mails to
|
40 |
| users of the application. Like the host we have set this value to
|
41 |
| stay compatible with the Mailgun e-mail application by default.
|
42 |
|
|
43 |
*/
|
44 |
|
45 |
'port' => env('MAIL_PORT', 587), |
46 |
|
47 |
/*
|
48 |
|--------------------------------------------------------------------------
|
49 |
| Global "From" Address
|
50 |
|--------------------------------------------------------------------------
|
51 |
|
|
52 |
| You may wish for all e-mails sent by your application to be sent from
|
53 |
| the same address. Here, you may specify a name and address that is
|
54 |
| used globally for all e-mails that are sent by your application.
|
55 |
|
|
56 |
*/
|
57 |
|
58 |
'from' => [ |
59 |
'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'), |
60 |
'name' => env('MAIL_FROM_NAME', 'Example'), |
61 |
],
|
62 |
|
63 |
/*
|
64 |
|--------------------------------------------------------------------------
|
65 |
| E-Mail Encryption Protocol
|
66 |
|--------------------------------------------------------------------------
|
67 |
|
|
68 |
| Here you may specify the encryption protocol that should be used when
|
69 |
| the application send e-mail messages. A sensible default using the
|
70 |
| transport layer security protocol should provide great security.
|
71 |
|
|
72 |
*/
|
73 |
|
74 |
'encryption' => env('MAIL_ENCRYPTION', 'tls'), |
75 |
|
76 |
/*
|
77 |
|--------------------------------------------------------------------------
|
78 |
| SMTP Server Username
|
79 |
|--------------------------------------------------------------------------
|
80 |
|
|
81 |
| If your SMTP server requires a username for authentication, you should
|
82 |
| set it here. This will get used to authenticate with your server on
|
83 |
| connection. You may also set the "password" value below this one.
|
84 |
|
|
85 |
*/
|
86 |
|
87 |
'username' => env('MAIL_USERNAME'), |
88 |
|
89 |
'password' => env('MAIL_PASSWORD'), |
90 |
|
91 |
/*
|
92 |
|--------------------------------------------------------------------------
|
93 |
| Sendmail System Path
|
94 |
|--------------------------------------------------------------------------
|
95 |
|
|
96 |
| When using the "sendmail" driver to send e-mails, we will need to know
|
97 |
| the path to where Sendmail lives on this server. A default path has
|
98 |
| been provided here, which will work well on most of your systems.
|
99 |
|
|
100 |
*/
|
101 |
|
102 |
'sendmail' => '/usr/sbin/sendmail -bs', |
103 |
|
104 |
/*
|
105 |
|--------------------------------------------------------------------------
|
106 |
| Markdown Mail Settings
|
107 |
|--------------------------------------------------------------------------
|
108 |
|
|
109 |
| If you are using Markdown based email rendering, you may configure your
|
110 |
| theme and component paths here, allowing you to customize the design
|
111 |
| of the emails. Or, you may simply stick with the Laravel defaults!
|
112 |
|
|
113 |
*/
|
114 |
|
115 |
'markdown' => [ |
116 |
'theme' => 'default', |
117 |
|
118 |
'paths' => [ |
119 |
resource_path('views/vendor/mail'), |
120 |
],
|
121 |
],
|
122 |
|
123 |
];
|
Cuando se trata de enviar emails, Laravel soporta diferentes controladores de los cuáles elegir. Como puedes ver, el MAIL_DRIVER por defecto está establecido a smtp.
Si vas a usar el controlador smtp para enviar correos entonces también se requiere establecer otros ajustes relacionados como MAIL_HOST, MAIL_PORT, MAIL_ENCRYPTION, MAIL_USERNAME, y MAIL_PASSWORD.
Por el otro lado, si vas a usar el controlador sendmail, entonces quieres asegurar que la ruta de sistema sendmail está establecida al valor correcto en el archivo config/mail.php.
También puedes establecer la dirección from que será usada mientras se mandan correos bajo la llave from. Y finalmente, si quieres usar generación de correo basado en marcado, puedes establecer esos ajustes bajo la llave markdown.
La cereza del pastel es que también podrías usar proveedores de correo de terceros como Mailgun, Mandrill, SES, y SparkPost. Si estás usando uno de esos servicios, necesitas asegurar que estableces los ajustes correspondientes en el archivo config/services.php.
Así que esa fue una introducción básica a los ajustes relacionados de API en Laravel. De la siguiente sección en adelante, iremos a través de un ejemplo personalizado que te muestra cómo enviar emails.
Crea la Clase Mailable
En esta sección, crearemos la clase mailable, la cuál será usada para enviar emails. La clase mailable es responsable de enviar emails usando un mailer que es configurado en el archivo config/mail.php. De hecho, Laravel ya proporciona un comando artisan que nos permite crear una plantilla base.
1 |
php artisan make:mail DemoEmail |
Eso debería crear una plantilla de email en blanco en app/Mail/DemoEmail.php, como se muestra en el siguiente código.
1 |
<?php
|
2 |
|
3 |
namespace App\Mail; |
4 |
|
5 |
use Illuminate\Bus\Queueable; |
6 |
use Illuminate\Mail\Mailable; |
7 |
use Illuminate\Queue\SerializesModels; |
8 |
use Illuminate\Contracts\Queue\ShouldQueue; |
9 |
|
10 |
class DemoEmail extends Mailable |
11 |
{
|
12 |
use Queueable, SerializesModels; |
13 |
|
14 |
/**
|
15 |
* Create a new message instance.
|
16 |
*
|
17 |
* @return void
|
18 |
*/
|
19 |
public function __construct() |
20 |
{
|
21 |
//
|
22 |
}
|
23 |
|
24 |
/**
|
25 |
* Build the message.
|
26 |
*
|
27 |
* @return $this
|
28 |
*/
|
29 |
public function build() |
30 |
{
|
31 |
return $this->view('view.name'); |
32 |
}
|
33 |
}
|
Reemplacemos los contenidos de ese archivo con lo siguiente.
1 |
<?php
|
2 |
|
3 |
namespace App\Mail; |
4 |
|
5 |
use Illuminate\Bus\Queueable; |
6 |
use Illuminate\Mail\Mailable; |
7 |
use Illuminate\Queue\SerializesModels; |
8 |
use Illuminate\Contracts\Queue\ShouldQueue; |
9 |
|
10 |
class DemoEmail extends Mailable |
11 |
{
|
12 |
use Queueable, SerializesModels; |
13 |
|
14 |
/**
|
15 |
* The demo object instance.
|
16 |
*
|
17 |
* @var Demo
|
18 |
*/
|
19 |
public $demo; |
20 |
|
21 |
/**
|
22 |
* Create a new message instance.
|
23 |
*
|
24 |
* @return void
|
25 |
*/
|
26 |
public function __construct($demo) |
27 |
{
|
28 |
$this->demo = $demo; |
29 |
}
|
30 |
|
31 |
/**
|
32 |
* Build the message.
|
33 |
*
|
34 |
* @return $this
|
35 |
*/
|
36 |
public function build() |
37 |
{
|
38 |
return $this->from('sender@example.com') |
39 |
->view('mails.demo') |
40 |
->text('mails.demo_plain') |
41 |
->with( |
42 |
[
|
43 |
'testVarOne' => '1', |
44 |
'testVarTwo' => '2', |
45 |
])
|
46 |
->attach(public_path('/images').'/demo.jpg', [ |
47 |
'as' => 'demo.jpg', |
48 |
'mime' => 'image/jpeg', |
49 |
]);
|
50 |
}
|
51 |
}
|
Hay dos métodos importantes que la clase mailable generalmente implementa---__construct y build. El método __construct es usado para inicializar objetos que se supone debes usar en la platilla de correo. Por el otro lado, el método build es usado para iniciar valores más específicos de email como de, vista de plantilla, adjuntos y similares.
En nuestro caso, hemos pasado el objeto $demo como un argumento de constructor, y está asignado a la propiedad pública demo.
En el método build, hemos iniciado una configuración específica de email.
- El
fromes usado para establecer una dirección de correo que será usada como una dirección de remitente. - Usando el método
view, puedes establecer la plantilla de email que será usada mientras se envía un email usando este mailable. En nuestro caso, lo establecimos amails.demo, y este significa que necesitas crear un archivo de vista de plantilla enresources/views/mails/demo.blade.php. - Después, el método
textes usado para establecer la versión de texto plano de una plantilla de email. - Como acabamos de discutir, el método
__constructes usado para establecer objetos que serán usados en la plantilla de email, también puedes usar el métodowithque te permite establecer los datos de vista de un mensaje. - Después, hemos usado el método
attachpara adjuntar una imagen con un mensaje.
Por supuesto, necesitamos crear plantillas de email que se supone usaremos mientras enviamos emails. Continua y crea un archivo resources/views/mails/demo.blade.php como se muestra en el siguiente código.
1 |
Hello <i>{{ $demo->receiver }}</i>, |
2 |
<p>This is a demo email for testing purposes! Also, it's the HTML version.</p> |
3 |
|
4 |
<p><u>Demo object values:</u></p> |
5 |
|
6 |
<div> |
7 |
<p><b>Demo One:</b> {{ $demo->demo_one }}</p> |
8 |
<p><b>Demo Two:</b> {{ $demo->demo_two }}</p> |
9 |
</div> |
10 |
|
11 |
<p><u>Values passed by With method:</u></p> |
12 |
|
13 |
<div> |
14 |
<p><b>testVarOne:</b> {{ $testVarOne }}</p> |
15 |
<p><b>testVarTwo:</b> {{ $testVarTwo }}</p> |
16 |
</div> |
17 |
|
18 |
Thank You, |
19 |
<br/> |
20 |
<i>{{ $demo->sender }}</i> |
También, creemos la versión de texto plano de ese archivo en resources/views/mails/demo_plain.blade.php.
1 |
Hello {{ $demo->receiver }}, |
2 |
This is a demo email for testing purposes! Also, it's the HTML version. |
3 |
|
4 |
Demo object values: |
5 |
|
6 |
Demo One: {{ $demo->demo_one }} |
7 |
Demo Two: {{ $demo->demo_two }} |
8 |
|
9 |
Values passed by With method: |
10 |
|
11 |
testVarOne: {{ $testVarOne }} |
12 |
testVarOne: {{ $testVarOne }} |
13 |
|
14 |
Thank You, |
15 |
{{ $demo->sender }} |
Así que esa fue la clase mailable a tu disposición, y no hemos terminado aún ya que necesitamos usar la fachada Mail para de hecho enviar correos. En la siguiente sección, exploraremos cómo puedes usar la Fachada Mail para enviar emials usando la clase Mailable DemoEmail que acabamos de crear en esta sección.
Terminando
En esta sección, crearemos un ejemplo para demostrar cómo puedes usar la clase Mailable que fue creada en la última sección.
Creemos un archivo controlador en app/Http/Controllers/MailController.php con los siguientes contenidos.
1 |
<?php
|
2 |
namespace App\Http\Controllers; |
3 |
|
4 |
use App\Http\Controllers\Controller; |
5 |
use App\Mail\DemoEmail; |
6 |
use Illuminate\Support\Facades\Mail; |
7 |
|
8 |
class MailController extends Controller |
9 |
{
|
10 |
public function send() |
11 |
{
|
12 |
$objDemo = new \stdClass(); |
13 |
$objDemo->demo_one = 'Demo One Value'; |
14 |
$objDemo->demo_two = 'Demo Two Value'; |
15 |
$objDemo->sender = 'SenderUserName'; |
16 |
$objDemo->receiver = 'ReceiverUserName'; |
17 |
|
18 |
Mail::to("receiver@example.com")->send(new DemoEmail($objDemo)); |
19 |
}
|
20 |
}
|
Es importante notar que hemos incluido la Fachada Illuminate\Support\Facades\Mail que será usada para enviar un email. En el método send, la siguiente declaración es responsable de enviar un correo inicializando el Mailable App\Mail\DemoEmail en el primer lugar.
1 |
Mail::to("receiver@example.com")->send(new DemoEmail($objDemo)); |
El método to de la Fachada Illuminate\Support\Facades\Mail devuelve una instancia de la clase \Illuminate\Mail\PendingMail, que ya contiene un mailer apropiado configurado en el archivo config/mail.php.
Y finalmente, usamos el método send de la clase \Illuminate\Mail\PendingMail que envía un email de verdad.
Para probarlo, agreguemos una ruta asociada en el archivo routes/web.php.
1 |
// Email related routes
|
2 |
Route::get('mail/send', 'MailController@send'); |
Y con eso en su lugar, puedes ejecutar la URL http://tu-sitio-laravel.com/mail/send para ver si funciona como se espera.
Por otro lado, si quieres probar tus plantillas de email rápidamente, sin enviar emails de verdad, hay una provisión en Laravel que te permite registrar todos los correos de salida.
Para lograr eso, necesitas establecer el valor de MAIL_DRIVER a log en el archivo config/mail.php. Después, podrías ejecutar la URL antes mencionada e inspeccionar el archivo de registro para revisar si la plantilla de email se registró ahí.
Si todo sale bien, deberías ver un email siendo registrado al archivo storage/logs/laravel.log.
Eso es prácticamente todo en cuanto a la característica de correo respecta en Laravel, y eso concluye este artículo también.
Conclusión
Hoy recorrimos la API de correo que viene integrada en Laravel, y esta también soporta una variedad de controladores.
Comenzando con conceptos básicos, implementamos la clase mailable que es un elemento esencial en la API de correo en Laravel a medida que avanzamos. Al final, también probamos la clase mailable creando un controlador personalizado para ver si funcionaba de verdad.
Si apenas estás comenzando con Laravel o estás buscando expandir tu conocimiento, sitio o aplicación con extensiones, tenemos una variedad de cosas que puedes estudiar en Envato Market.
¡Me encantaría conocer tu retroalimentación en la forma de peticiones y comentarios usando la sección de abajo!
By
