Mục lục
Mục lục này tương ứng với mục lục trên trang chủ của Laravel.
-
Mở đầu
- Release Notes
- Upgrade Guide
- Contribution Guide
- API Documentation
-
Thiết lập
-
Hướng dẫn
-
Cơ bản
- Routing
- Middleware
- Controllers
- Requests
- Responses
- Views
- Blade Templates
-
Nền tảng kiến trúc
-
Services
- Authentication
- Authorization
- Artisan Console
- Billing
- Cache
- Collections
- Elixir
- Encryption
- Errors & Logging
- Events
- Filesystem & Cloud Storage
- Hashing
- Helpers
- Localization
- Package Development
- Pagination
- Queues
- Redis
- Envoy or SSH Tasks
- Task Scheduling
- Testing
- Validation
-
Database
- Getting Started
- Query Builder
- Migrations
- Seeding
-
Eloquent ORM
Giới thiệu
Laravel cung cấp API rất gọn và đơn giản thông qua thư viện SwiftMailer nổi tiếng. Laravel về cơ bản cung cấp driver cho SMTP, Mailgun, Mandrill, SparkPost, Amazon SES, hàm mail
của PHP, và sendmail
, cho phép bạn nhanh chóng bắt đầu gửi mail qua dịch vụ mail local hay cloud tuỳ theo lựa chọn của bạn.
Yêu cầu cho driver
Các driver dựa trên API như Mailgun hay Mandrill thường đơn giản và nhanh hơn SMTP server. Tất cả các API driver yêu cầu sử dụng thư viện Guzzle HTTP được cài đặt trong ứng dụng của bạn. Bạn có thể cài đặt vào project bằng cách thêm dòng dưới đây vào trong file composer.json
:
"guzzlehttp/guzzle": "~5.3|~6.0"
Mailgun Driver
Để sử dụng Mailgun driver, đầu tiên cài Guzzle, rồi set giá trị driver
ở trong file config/mail.php
thành mailgun
. Tiếp đó, xác nhận thông tin sau trong file config/services.php
:
'mailgun' => [
'domain' => 'your-mailgun-domain',
'secret' => 'your-mailgun-key',
],
Mandrill Driver
Để sử dụng Mandrill driver, đầu tiên cài Guzzle, rồi set giá trị driver
trong config/mail.php
thành mandrill
. Sau đó, xác nhận thông tin sau trong file config/services.php
:
'mandrill' => [
'secret' => 'your-mandrill-key',
],
SparkPost Driver
Để sử dụng SparkPost driver, đầu tiên cài Guzzle, rồi set giá trị driver
trong file config/mail.php
thành sparkpost
. Tiếp đó, xác nhận thông tin sau trong file cấu hình config/services.php
:
'sparkpost' => [
'secret' => 'your-sparkpost-key',
],
SES Driver
Để sử dụng Amazon SES driver, cài Amazon AWS SDK cho PHP. Bạn có thể cài thư viện này bằng cách thêm dòng dưới đây vào trong file composer.json
ở mục require
:
"aws/aws-sdk-php": "~3.0"
Sau đó, set giá trị driver
trong file config/mail.php
thành ses
. Sau đó, xác nhận các thông số dưới đây trong file cấu hình config/services.php
:
'ses' => [
'key' => 'your-ses-key',
'secret' => 'your-ses-secret',
'region' => 'ses-region', // e.g. us-east-1
],
Sending Mail
Laravel cho phép bạn lưu bản tin email trong views. Ví dụ, để quản lý emails, bạn có thể tạo thư mục emails
bên trong thư mục resources/views
.
Để gửi một bản tin, sử dụng hàm send
trong Mail
facade. Hàm send
nhận ba tham số. Tham số đầu tiên, là tên của view mà chứa nội dung của email. Tham số thứ hai là một mảng data mà bạn muốn truyền vào trong view. Cuối cùng là một Closure
trong đó có nhận một instance của message, cho phép bạn tuỳ chỉnh thông tin recipients, subject và các thông tin khác của một bản tin email:
<?php
namespace App\Http\Controllers;
use Mail;
use App\User;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class UserController extends Controller
{
/**
* Send an e-mail reminder to the user.
*
* @param Request $request
* @param int $id
* @return Response
*/
public function sendEmailReminder(Request $request, $id)
{
$user = User::findOrFail($id);
Mail::send('emails.reminder', ['user' => $user], function ($m) use ($user) {
$m->from('[email protected]', 'Your Application');
$m->to($user->email, $user->name)->subject('Your Reminder!');
});
}
}
Khi chúng ta truyền vào một mảng chứa khoá user
trong ví dụ ở trên, chúng ta có thể hiển thị tên của usser bên trong view của email sử dụng đoạn mã PHP sau:
<?php echo $user->name; ?>
Lưu ý: Một biến
$message
luôn được truyền vào views của emails, và cho phép nhúng trực tiếp file đính kèm. Vì thế, bạn nên tránh truyền biến$message
vào trong view payload.
Tạo bản tin
Như bàn ở trước, tham số thứ ba truyền vào trong hàm send
là một Closure
cho phép bạn chỉ định nhiều thông số cho email. Với Closure này, bạn có thể truyền vào các thuộc tính cho bản tin như CC, BCC...
Mail::send('emails.welcome', $data, function ($message) {
$message->from('[email protected]', 'Laravel');
$message->to('[email protected]')->cc('[email protected]');
});
Đây là danh sách các hàm có thể sử dụng trong biến $message
:
$message->from($address, $name = null);
$message->sender($address, $name = null);
$message->to($address, $name = null);
$message->cc($address, $name = null);
$message->bcc($address, $name = null);
$message->replyTo($address, $name = null);
$message->subject($subject);
$message->priority($level);
$message->attach($pathToFile, array $options = []);
// Attach a file from a raw $data string...
$message->attachData($data, $name, array $options = []);
// Get the underlying SwiftMailer message instance...
$message->getSwiftMessage();
Lưu ý: Instance
$message
được truyền choMail::send
Closure mở rộng class message của SwiftMailer, cho phép bạn gọi bất cứ hàm nào của class đó để tạo nội dung bản tin cho email.
Gửi mail dạng text
Mặc định, view được truyền vào hàm send
là dạng HTML. Tuy nhiên, bằng cách truyền vào một mảng vào tham số đầu của hàm send
, bạn có thể chỉ định một view text để gửi bổ sung với HTML view:
Mail::send(['html.view', 'text.view'], $data, $callback);
Hoặc, nếu bạn chỉ muốn email dạng text, bạn chỉ cần sử dụng khoá text
trong mảng:
Mail::send(['text' => 'view'], $data, $callback);
Gửi mail dạng chuỗi
Bạn có thể sử dụng hàm raw
nếu muốn gửi một email dạng chuỗi trực tiếp:
Mail::raw('Text to e-mail', function ($message) {
//
});
Các file đính kèm
Để thêm đính kèm vào một email, sử dụng hàm attach
của $message
truyền trong Closure. Hàm attach
nhận đường dẫn đầy đủ tới file ở tham số đầu:
Mail::send('emails.welcome', $data, function ($message) {
//
$message->attach($pathToFile);
});
Khi đính kèm files tới một bản tin, bạn cũng có thể chỉ định tên hiển thị hay / hoặc MIME type bằng cách truyền vào một array
ở tham số thứ hai trong hàm attach
:
$message->attach($pathToFile, ['as' => $display, 'mime' => $mime]);
Đính kèm inline
Nhúng ảnh vào trong view của email
Nhúng ảnh vào trong email về cơ bản là khá rườm rà; tuy nhiên, Laravel cung cấp sẵn một khá tiện lợi để nhúng ảnh vào trong mail và lấy ra sử dụng CID hơp lí. Để nhúng vào một ảnh inline, sử dụng hàm embed
của biến $message
bên trong email view. Nhớ rằng, Laravel tự động làm cho biến $message
có thể sử dụng được trong tất cả các view của email:
<body>
Here is an image:
<img src="<?php echo $message->embed($pathToFile); ?>">
</body>
Nhúng dữ liệu thô vào trong email view
Nếu bạn đã có sẵn chuỗi dữ liệu thô và muốn nhúng vào trong bản tin email, bạn có thể sử dụng hàm embedData
cho biến $message
:
<body>
Here is an image from raw data:
<img src="<?php echo $message->embedData($data, $name); ?>">
</body>
Sử dụng queue gửi mail
Thực hiện queue một bản tin email
Vì việc gửi email sẽ làm tăng thời gian response của ứng dụng, nhiều lập trình viên chọn cách sử dụng queue cho bản tin email để gửi ở background. Laravel làm cho điều này khá dễ dàng sử dụng API thống nhất cho queue. Để queue một bản tin mail, sử dụng hàm queue
trong Mail
facade:
Mail::queue('emails.welcome', $data, function ($message) {
//
});
Hàm này sẽ tự động lo việc đẩy job vào trong queue để gửi tin nhắn trong background. Dĩ nhiên, bạn sẽ cần thực hiện cấu hình queue trước khi sử dụng tính năng này.
Trì hoãn việc queue mail
Nếu bạn muốn trì hoãn việc gửi các bản tin email đã được queue, bạn có thể sử dụng hàm later
. Để bắt đầu, đơn giản chỉ cần truyền vào số giây mà bạn muốn trì hoãn việc gửi bản tin trong tham số đâu tiên của hàm:
Mail::later(5, 'emails.welcome', $data, function ($message) {
//
});
Đẩy vào một queue cụ thể
Nếu bạn muốn đẩy vào một queue cụ thể, bạn sử dụng hàm queueOn
và laterOn
:
Mail::queueOn('queue-name', 'emails.welcome', $data, function ($message) {
//
});
Mail::laterOn('queue-name', 5, 'emails.welcome', $data, function ($message) {
//
});
Mail & Local Development
Khi phát triển ứng dụng có gửi email, bạn có thể không muốn thực sự gửi email tới địa chỉ thực. Laravel hỗ trợ vài cách để "vô hiệu hoá" việc gửi email này.
Log Driver
One solution is to use the log
mail driver during local development. This driver will write all e-mail messages to your log files for inspection. For more information on configuring your application per environment, check out the configuration documentation.
Một phương án là sử dụng driver log
trong môi trường phát triển local. Driver này sẽ viết các bản tin emails vào trong log file để kiểm tra. Để tìm hiểu thêm thông tin về cấu hình ứng dụng cho từng môi trường, xem mục cấu hình.
Universal To
Một cách khác được Laravel cung cấp đó là thiết lập một recipient toàn cục cho tất cả các email được framework gửi đi. Với cách này, tất cả các mail được tạo bởi ứng dụng sẽ được gửi tới một địa chỉ cụ thể, thay vì địa chỉ được ghi khi gửi mail. Việc này có thể thực hiện thông qua tuỳ chọn to
trong file cấu hình config/mail.php
:
'to' => [
'address' => '[email protected]',
'name' => 'Dev Example'
],
Mailtrap
Cuối cùng, bản có thể sử dụng dịch vụ bên ngoài như Mailtrap với driver là smtp
để gửi email tới một hộp thư "dummy" mà bạn có thể coi nội dung trên một email client thật. Phương pháp này có lợi ích là cho phép bạn xem email cuối cùng được gửi đi và nhìn nội dung như thế nào trên Mailtrap.
Events
Laravel bắn ra một event trước khi gửi bản tin mail. Hãy nhớ là, event này được bắn ra khi mail đã được gửi đi, chứ không phải lúc được queue. Bạn có thể đăng kí event listener tới event này trong EventServiceProvider
:
/**
* The event listener mappings for the application.
*
* @var array
*/
protected $listen = [
'Illuminate\Mail\Events\MessageSending' => [
'App\Listeners\LogSentMessage',
],
];