ایمیل

• معرفی
  • پیکربندی
  • پیش نیاز راننده
  • پیکربندی Failover
• تولید Mailables
• نوشتن Mailables
  • پیکربندی فرستنده
  • پیکربندی نمای
  • مشاهده داده ها
  • پیوست ها
  • پیوست های درون خطی
  • سفارشی کردن پیام SwiftMailer
• Markdown Mailables
  • ایجاد Markdown Mailables
  • نوشتن پیام های علامت گذاری
  • سفارشی سازی کامپوننت ها
• ارسال نامه
  • نامه در صف
• ارائه Mailables
  • پیش نمایش ایمیل ها در مرورگر
• بومی سازی Mailables
• تست Mailables
• ایمیل و توسعه محلی
• مناسبت ها

معرفی

ارسال ایمیل نباید پیچیده باشد. لاراول یک API ایمیل ساده و تمیز ارائه می دهد که توسط کتابخانه محبوب SwiftMailer پشتیبانی می شود . Laravel و SwiftMailer درایورهایی برای ارسال ایمیل از طریق SMTP، Mailgun، Postmark، Amazon SES و . به sendmail شما این امکان را می دهند که به سرعت ارسال نامه را از طریق یک سرویس محلی یا مبتنی بر ابر انتخابی خود شروع کنید.

پیکربندی

سرویس های ایمیل لاراول ممکن است از طریق config/mail.php فایل پیکربندی برنامه شما پیکربندی شوند. هر ایمیلی که در این فایل پیکربندی شده است ممکن است پیکربندی منحصربه‌فرد خود و حتی "حمل و نقل" منحصربه‌فرد خود را داشته باشد که به برنامه شما اجازه می‌دهد از سرویس‌های ایمیل مختلف برای ارسال پیام‌های ایمیل خاص استفاده کند. به عنوان مثال، برنامه شما ممکن است از Postmark برای ارسال ایمیل های تراکنشی استفاده کند در حالی که از Amazon SES برای ارسال ایمیل های انبوه استفاده می کند.

در mail فایل پیکربندی خود، یک آرایه پیکربندی پیدا خواهید کرد mailers . این آرایه شامل یک ورودی پیکربندی نمونه برای هر یک از درایورهای اصلی ایمیل / حمل و نقل های پشتیبانی شده توسط لاراول است، در حالی که مقدار default پیکربندی تعیین می کند که زمانی که برنامه شما نیاز به ارسال یک پیام ایمیل داشته باشد، کدام ایمیل به طور پیش فرض استفاده می شود.

پیش نیاز راننده / حمل و نقل

درایورهای مبتنی بر API مانند Mailgun و Postmark اغلب ساده تر و سریعتر از ارسال نامه از طریق سرورهای SMTP هستند. در صورت امکان، توصیه می کنیم از یکی از این درایورها استفاده کنید. همه درایورهای مبتنی بر API به کتابخانه HTTP Guzzle نیاز دارند که ممکن است از طریق مدیر بسته Composer نصب شود:

composer require guzzlehttp/guzzle

درایور تفنگ پستی

برای استفاده از درایور Mailgun، ابتدا کتابخانه Guzzle HTTP را نصب کنید. سپس default گزینه موجود در config/mail.php فایل پیکربندی خود را روی mailgun . در مرحله بعد، بررسی کنید که فایل پیکربندی شما config/services.php حاوی گزینه های زیر باشد:

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
],

اگر از منطقه Mailgun ایالات متحده استفاده نمی کنید ، می توانید نقطه پایانی منطقه خود را در services فایل پیکربندی تعریف کنید:

'mailgun' => [
    'domain' => env('MAILGUN_DOMAIN'),
    'secret' => env('MAILGUN_SECRET'),
    'endpoint' => env('MAILGUN_ENDPOINT', 'api.eu.mailgun.net'),
],

درایور علامت پست

برای استفاده از درایور Postmark، انتقال SwiftMailer Postmark را از طریق Composer نصب کنید:

composer require wildbit/swiftmailer-postmark

در مرحله بعد، کتابخانه HTTP Guzzle را نصب کنید و default گزینه موجود در config/mail.php فایل پیکربندی خود را روی postmark . در نهایت، بررسی کنید که فایل پیکربندی شما config/services.php حاوی گزینه های زیر باشد:

'postmark' => [
    'token' => env('POSTMARK_TOKEN'),
],

اگر می‌خواهید جریان پیام Postmark را مشخص کنید که باید توسط یک پست‌کننده معین استفاده شود، می‌توانید message_stream_id گزینه پیکربندی را به آرایه پیکربندی پست‌کننده اضافه کنید. این آرایه پیکربندی را می توان در فایل پیکربندی برنامه شما یافت config/mail.php :

'postmark' => [
    'transport' => 'postmark',
    'message_stream_id' => env('POSTMARK_MESSAGE_STREAM_ID'),
],

به این ترتیب شما همچنین می توانید چندین ایمیل پست مارک را با جریان های مختلف پیام راه اندازی کنید.

درایور SES

برای استفاده از درایور Amazon SES ابتدا باید Amazon AWS SDK برای PHP را نصب کنید. می توانید این کتابخانه را از طریق مدیر بسته Composer نصب کنید:

composer require aws/aws-sdk-php

در مرحله بعد، گزینه موجود در فایل پیکربندی default خود را روی آن تنظیم کنید و بررسی کنید که فایل پیکربندی شما حاوی گزینه های زیر باشد: config/mail.php ses config/services.php

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
],

برای استفاده از اعتبارنامه های موقت AWS از طریق یک نشانه جلسه، می توانید یک token کلید به پیکربندی SES برنامه خود اضافه کنید:

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'token' => env('AWS_SESSION_TOKEN'),
],

اگر می خواهید گزینه های دیگری را SendRawEmail تعریف کنید که لاراول باید هنگام ارسال ایمیل به متد AWS SDK منتقل کند ، می توانید یک options آرایه در ses پیکربندی خود تعریف کنید:

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'options' => [
        'ConfigurationSetName' => 'MyConfigurationSet',
        'Tags' => [
            ['Name' => 'foo', 'Value' => 'bar'],
        ],
    ],
],

پیکربندی Failover

گاهی اوقات، ممکن است یک سرویس خارجی که برای ارسال ایمیل برنامه خود پیکربندی کرده اید، از کار افتاده باشد. در این موارد، تعریف یک یا چند پیکربندی تحویل نامه پشتیبان می تواند مفید باشد که در صورتی که درایور تحویل اولیه شما خراب باشد، استفاده می شود.

برای انجام این کار، باید یک میلر را در فایل پیکربندی برنامه خود تعریف کنید mail که از failover انتقال استفاده می کند. آرایه پیکربندی برای ایمیل برنامه شما failover باید دارای آرایه ای از mailers آن مرجع باشد که در آن درایورهای نامه باید برای تحویل انتخاب شوند:

'mailers' => [
    'failover' => [
        'transport' => 'failover',
        'mailers' => [
            'postmark',
            'mailgun',
            'sendmail',
        ],
    ],
 
    // ...
],

هنگامی که ایمیل‌کننده شکست‌خورده شما تعریف شد، باید با تعیین نام آن به‌عنوان مقدار default کلید پیکربندی در mail فایل پیکربندی برنامه، این میل را به‌عنوان پست‌کننده پیش‌فرض مورد استفاده توسط برنامه خود تنظیم کنید:

'default' => env('MAIL_MAILER', 'failover'),

تولید Mailables

هنگام ساخت برنامه های لاراول، هر نوع ایمیلی که توسط برنامه شما ارسال می شود به عنوان یک کلاس "mailable" نمایش داده می شود. این کلاس ها در app/Mail دایرکتوری ذخیره می شوند. اگر این دایرکتوری را در برنامه خود نمی بینید نگران نباشید، زیرا زمانی که اولین کلاس پستی خود را با استفاده از make:mail دستور Artisan ایجاد می کنید برای شما ایجاد می شود:

php artisan make:mail OrderShipped

نوشتن Mailables

هنگامی که یک کلاس پستی ایجاد کردید، آن را باز کنید تا بتوانیم محتوای آن را بررسی کنیم. ابتدا توجه داشته باشید که تمام پیکربندی یک کلاس mailable در build متد انجام می شود. در این روش، می‌توانید با روش‌های مختلفی مانند from ،،، و برای پیکربندی نمایش و تحویل ایمیل تماس بگیرید. subject view attach

می‌توانید وابستگی‌ها را به روش پست‌پذیر تایپ کنید build . ظرف سرویس لاراول به طور خودکار این وابستگی ها را تزریق می کند.

پیکربندی فرستنده

استفاده از from روش

ابتدا اجازه دهید پیکربندی فرستنده ایمیل را بررسی کنیم. یا به عبارت دیگر، ایمیل قرار است "از طرف" چه کسی باشد. دو راه برای پیکربندی فرستنده وجود دارد. ابتدا، می توانید از from متد در متد کلاس mailable خود استفاده کنید build :

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->from('example@example.com', 'Example')
                ->view('emails.orders.shipped');
}

from استفاده از یک آدرس جهانی

با این حال، اگر برنامه شما از همان آدرس «از» برای همه ایمیل‌های خود استفاده کند، فراخوانی روش from در هر کلاس پستی که ایجاد می‌کنید می‌تواند دشوار شود. در عوض، می‌توانید یک آدرس جهانی «از» را در config/mail.php فایل پیکربندی خود مشخص کنید. این آدرس در صورتی استفاده خواهد شد که هیچ آدرس دیگری از "from" در کلاس mailable مشخص نشده باشد:

'from' => ['address' => 'example@example.com', 'name' => 'App Name'],

علاوه بر این، می توانید یک آدرس جهانی "reply_to" را در config/mail.php فایل پیکربندی خود تعریف کنید:

'reply_to' => ['address' => 'example@example.com', 'name' => 'App Name'],

پیکربندی نمای

در یک متد کلاس mailable build ، می‌توانید از این view روش برای تعیین الگوی مورد استفاده در هنگام رندر کردن محتوای ایمیل استفاده کنید. از آنجایی که هر ایمیل معمولاً از یک الگوی Blade برای ارائه محتوای خود استفاده می کند، هنگام ساخت HTML ایمیل خود از قدرت و راحتی موتور قالب Blade برخوردار هستید:

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

ممکن است بخواهید یک resources/views/emails دایرکتوری ایجاد کنید تا همه الگوهای ایمیل خود را در خود جای دهد. با این حال، شما آزاد هستید که آنها را در هر کجا که می خواهید در resources/views فهرست خود قرار دهید.

ایمیل های متن ساده

اگر می خواهید یک نسخه متنی ایمیل خود را تعریف کنید، می توانید از این text روش استفاده کنید. مانند view روش، این text روش یک نام الگو را می پذیرد که برای ارائه محتوای ایمیل استفاده می شود. شما آزاد هستید که هم نسخه HTML و هم متن ساده پیام خود را تعریف کنید:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->text('emails.orders.shipped_plain');
}

مشاهده داده ها

از طریق املاک عمومی

به طور معمول، شما می خواهید برخی از داده ها را به نمای خود ارسال کنید که می توانید هنگام رندر HTML ایمیل از آنها استفاده کنید. دو راه وجود دارد که می‌توانید داده‌ها را در دسترس خود قرار دهید. ابتدا، هر ویژگی عمومی تعریف شده در کلاس mailable شما به طور خودکار در دسترس view قرار می گیرد. بنابراین، برای مثال، می‌توانید داده‌ها را به سازنده کلاس mailable خود ارسال کنید و آن داده‌ها را روی ویژگی‌های عمومی تعریف شده در کلاس تنظیم کنید:

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * The order instance.
     *
     * @var \App\Models\Order
     */
    public $order;
 
    /**
     * Create a new message instance.
     *
     * @param  \App\Models\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }
 
    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('emails.orders.shipped');
    }
}

هنگامی که داده ها روی یک ویژگی عمومی تنظیم شدند، به طور خودکار در دید شما در دسترس خواهند بود، بنابراین می توانید مانند سایر داده های موجود در قالب های Blade به آن دسترسی داشته باشید:

<div>
    Price: {{ $order->price }}
</div>

از طریق with روش:

اگر می‌خواهید فرمت داده‌های ایمیل خود را قبل از ارسال به الگو سفارشی کنید، می‌توانید به صورت دستی داده‌های خود را از طریق روش به نمایش ارسال کنید with . به طور معمول، شما همچنان داده ها را از طریق سازنده کلاس mailable ارسال می کنید. با این حال، باید این داده ها را روی protected یا private ویژگی ها تنظیم کنید تا داده ها به طور خودکار در دسترس الگو قرار نگیرند. سپس، هنگام فراخوانی with متد، آرایه ای از داده ها را که می خواهید در دسترس الگو قرار دهید، ارسال کنید:

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * The order instance.
     *
     * @var \App\Models\Order
     */
    protected $order;
 
    /**
     * Create a new message instance.
     *
     * @param  \App\Models\Order  $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }
 
    /**
     * Build the message.
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('emails.orders.shipped')
                    ->with([
                        'orderName' => $this->order->name,
                        'orderPrice' => $this->order->price,
                    ]);
    }
}

هنگامی که داده ها به روش منتقل شدند with ، به طور خودکار در دید شما در دسترس خواهند بود، بنابراین می توانید مانند سایر داده های موجود در قالب های Blade به آن دسترسی داشته باشید:

<div>
    Price: {{ $orderPrice }}
</div>

پیوست ها

برای افزودن پیوست به ایمیل، از attach متد موجود در متد mailable class استفاده کنید build . متد attach مسیر کامل فایل را به عنوان اولین آرگومان خود می پذیرد:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attach('/path/to/file');
}

هنگام پیوست کردن فایل‌ها به پیام، می‌توانید نام نمایشی و/یا نوع MIME را با ارسال یک array آرگومان دوم به attach روش مشخص کنید:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attach('/path/to/file', [
                    'as' => 'name.pdf',
                    'mime' => 'application/pdf',
                ]);
}

پیوست کردن فایل ها از دیسک

اگر فایلی را روی یکی از دیسک های سیستم فایل خود ذخیره کرده اید ، می توانید آن را با استفاده از attachFromStorage روش زیر به ایمیل پیوست کنید:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
   return $this->view('emails.orders.shipped')
               ->attachFromStorage('/path/to/file');
}

در صورت لزوم، می‌توانید نام پیوست فایل و گزینه‌های اضافی را با استفاده از آرگومان‌های دوم و سوم متد مشخص کنید attachFromStorage :

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
   return $this->view('emails.orders.shipped')
               ->attachFromStorage('/path/to/file', 'name.pdf', [
                   'mime' => 'application/pdf'
               ]);
}

attachFromStorageDisk اگر نیاز به تعیین دیسک ذخیره سازی غیر از دیسک پیش فرض خود داشته باشید، ممکن است از این روش استفاده شود:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
   return $this->view('emails.orders.shipped')
               ->attachFromStorageDisk('s3', '/path/to/file');
}

پیوست های داده های خام

این attachData روش ممکن است برای پیوست کردن یک رشته خام از بایت ها به عنوان پیوست استفاده شود. به عنوان مثال، اگر PDF در حافظه ایجاد کرده اید و می خواهید آن را بدون نوشتن روی دیسک به ایمیل پیوست کنید، ممکن است از این روش استفاده کنید. متد attachData بایت های داده خام را به عنوان آرگومان اول، نام فایل را به عنوان آرگومان دوم و آرایه ای از گزینه ها را به عنوان آرگومان سوم می پذیرد:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attachData($this->pdf, 'name.pdf', [
                    'mime' => 'application/pdf',
                ]);
}

پیوست های درون خطی

تعبیه تصاویر درون خطی در ایمیل‌های شما معمولاً دشوار است. با این حال، لاراول یک راه راحت برای پیوست کردن تصاویر به ایمیل های شما ارائه می دهد. برای جاسازی یک تصویر درون خطی، از embed روش روی $message متغیر درون قالب ایمیل خود استفاده کنید. لاراول به طور خودکار $message متغیر را در دسترس همه قالب های ایمیل شما قرار می دهد، بنابراین نیازی نیست نگران ارسال دستی آن باشید:

<body>
    Here is an image:
 
    <img src="{{ $message->embed($pathToImage) }}">
</body>

این $message متغیر در قالب های پیام متنی ساده موجود نیست زیرا پیام های متنی ساده از پیوست های درون خطی استفاده نمی کنند.

تعبیه پیوست های داده خام

اگر از قبل یک رشته داده تصویر خام دارید که می‌خواهید در قالب ایمیل جاسازی کنید، می‌توانید embedData روش روی $message متغیر را فراخوانی کنید. هنگام فراخوانی embedData متد، باید یک نام فایل ارائه کنید که باید به تصویر تعبیه شده اختصاص داده شود:

<body>
    Here is an image from raw data:
 
    <img src="{{ $message->embedData($data, 'example-image.jpg') }}">
</body>

سفارشی کردن پیام SwiftMailer

متد withSwiftMessage کلاس Mailable پایه به شما امکان می دهد تا یک بسته را ثبت کنید که قبل از ارسال پیام با نمونه پیام SwiftMailer فراخوانی می شود. این به شما فرصتی می دهد تا پیام را قبل از تحویل عمیقاً شخصی سازی کنید:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    $this->view('emails.orders.shipped');
 
    $this->withSwiftMessage(function ($message) {
        $message->getHeaders()->addTextHeader(
            'Custom-Header', 'Header Value'
        );
    });
 
    return $this;
}

Markdown Mailables

پیام‌های پستی Markdown به شما این امکان را می‌دهند که از الگوهای از پیش ساخته شده و مؤلفه‌های اعلان‌های ایمیل در فایل‌های پستی خود استفاده کنید. از آنجایی که پیام‌ها در Markdown نوشته می‌شوند، لاراول می‌تواند قالب‌های زیبا و پاسخ‌گوی HTML را برای پیام‌ها ارائه کند و در عین حال به‌طور خودکار یک متن ساده نیز تولید کند.

ایجاد Markdown Mailables

برای ایجاد پستی با یک الگوی Markdown مربوطه، می توانید --markdown از گزینه make:mail دستور Artisan استفاده کنید:

php artisan make:mail OrderShipped --markdown=emails.orders.shipped

سپس، هنگام پیکربندی mailable در build متد آن، markdown متد را به جای view متد فراخوانی کنید. این markdown روش نام الگوی Markdown و یک آرایه اختیاری از داده‌ها را برای در دسترس قرار دادن الگو می‌پذیرد:

/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    return $this->from('example@example.com')
                ->markdown('emails.orders.shipped', [
                    'url' => $this->orderUrl,
                ]);
}

نوشتن پیام های علامت گذاری

پست‌های Markdown از ترکیب اجزای Blade و نحو Markdown استفاده می‌کنند که به شما امکان می‌دهد به راحتی پیام‌های ایمیل بسازید در حالی که از اجزای رابط کاربری ایمیل از پیش ساخته شده لاراول استفاده می‌کنید:

@component('mail::message')
# Order Shipped
 
Your order has been shipped!
 
@component('mail::button', ['url' => $url])
View Order
@endcomponent
 
Thanks,<br>
{{ config('app.name') }}
@endcomponent

هنگام نوشتن ایمیل های Markdown از تورفتگی بیش از حد استفاده نکنید. طبق استانداردهای Markdown، تجزیه کننده های Markdown محتوای تورفتگی را به عنوان بلوک های کد ارائه می کنند.

جزء دکمه

جزء دکمه یک پیوند دکمه مرکزی را ارائه می دهد. مؤلفه دو آرگومان a url و اختیاری را می پذیرد color . رنگ های پشتیبانی شده عبارتند از primary , success , و error . شما می توانید به تعداد دلخواه اجزای دکمه را به پیام اضافه کنید:

@component('mail::button', ['url' => $url, 'color' => 'success'])
View Order
@endcomponent

جزء پنل

مؤلفه پانل بلوک متن داده شده را در پانلی ارائه می دهد که رنگ پس زمینه کمی متفاوت از بقیه پیام دارد. این به شما امکان می دهد توجه را به یک بلوک متن معین جلب کنید:

@component('mail::panel')
This is the panel content.
@endcomponent

جزء جدول

جزء جدول به شما امکان می دهد یک جدول Markdown را به یک جدول HTML تبدیل کنید. کامپوننت جدول Markdown را به عنوان محتوای خود می پذیرد. تراز ستون جدول با استفاده از نحو پیش فرض تراز جدول Markdown پشتیبانی می شود:

@component('mail::table')
| Laravel       | Table         | Example  |
| ------------- |:-------------:| --------:|
| Col 2 is      | Centered      | $10      |
| Col 3 is      | Right-Aligned | $20      |
@endcomponent

سفارشی سازی کامپوننت ها

شما می توانید تمام اجزای ایمیل Markdown را برای سفارشی سازی به برنامه شخصی خود صادر کنید. برای صادرات کامپوننت ها، از vendor:publish دستور Artisan برای انتشار laravel-mail تگ دارایی استفاده کنید:

php artisan vendor:publish --tag=laravel-mail

این دستور اجزای ایمیل Markdown را در resources/views/vendor/mail دایرکتوری منتشر می کند. دایرکتوری mail شامل یک دایرکتوری html و یک text دایرکتوری خواهد بود که هر کدام شامل نمایش های مربوط به هر جزء موجود می باشد. شما آزاد هستید که این اجزا را هر طور که دوست دارید سفارشی کنید.

سفارشی کردن CSS

پس از صادرات اجزاء، resources/views/vendor/mail/html/themes دایرکتوری حاوی یک default.css فایل خواهد بود. می‌توانید CSS را در این فایل سفارشی کنید و سبک‌های شما به‌طور خودکار به سبک‌های CSS درون‌خطی در نمایش‌های HTML پیام‌های ایمیل Markdown شما تبدیل می‌شوند.

اگر می‌خواهید یک موضوع کاملاً جدید برای اجزای Markdown لاراول بسازید، می‌توانید یک فایل CSS را در html/themes دایرکتوری قرار دهید. پس از نامگذاری و ذخیره فایل CSS، theme گزینه فایل پیکربندی برنامه خود را به روز کنید config/mail.php تا با نام موضوع جدید شما مطابقت داشته باشد.

برای سفارشی کردن تم برای هر پستی، می توانید $theme ویژگی کلاس mailable را به نام موضوعی که باید هنگام ارسال آن پستی استفاده شود، تنظیم کنید.

ارسال نامه

برای ارسال پیام از روش نما to استفاده کنید . این روش یک آدرس ایمیل، یک نمونه کاربر یا مجموعه ای از کاربران را می پذیرد. اگر یک شی یا مجموعه ای از اشیاء را ارسال کنید، پست کننده به طور خودکار از ویژگی ها و ویژگی های آنها هنگام تعیین گیرندگان ایمیل استفاده می کند، بنابراین مطمئن شوید که این ویژگی ها در اشیاء شما موجود است. هنگامی که گیرندگان خود را مشخص کردید، می توانید نمونه ای از کلاس mailable خود را به متد ارسال کنید: Mail to email name send

<?php
 
namespace App\Http\Controllers;
 
use App\Http\Controllers\Controller;
use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
 
class OrderShipmentController extends Controller
{
    /**
     * Ship the given order.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function store(Request $request)
    {
        $order = Order::findOrFail($request->order_id);
 
        // Ship the order...
 
        Mail::to($request->user())->send(new OrderShipped($order));
    }
}

شما فقط محدود به تعیین گیرندگان "to" در هنگام ارسال پیام نیستید. شما آزاد هستید که گیرندگان «to»، «cc» و «bcc» را با زنجیره‌ای کردن روش‌های مربوطه به یکدیگر تنظیم کنید:

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->send(new OrderShipped($order));

حلقه روی گیرندگان

گاهی اوقات، ممکن است لازم باشد با تکرار روی آرایه‌ای از گیرندگان/آدرس‌های ایمیل، یک پست قابل ارسال به فهرستی از گیرندگان ارسال کنید. با این حال، از آنجایی که این to روش آدرس‌های ایمیل را به لیست دریافت‌کنندگان پست‌پذیر اضافه می‌کند، هر تکرار از طریق حلقه، ایمیل دیگری را برای هر گیرنده قبلی ارسال می‌کند. بنابراین، همیشه باید نمونه پستی را برای هر گیرنده دوباره ایجاد کنید:

foreach (['taylor@example.com', 'dries@example.com'] as $recipient) {
    Mail::to($recipient)->send(new OrderShipped($order));
}

ارسال نامه از طریق یک میلر خاص

به‌طور پیش‌فرض، لاراول با استفاده از ایمیلی که به‌عنوان default پست‌کننده در فایل پیکربندی برنامه شما پیکربندی شده است، ایمیل ارسال می‌کند mail . با این حال، می توانید از این mailer روش برای ارسال پیام با استفاده از یک پیکربندی ایمیل خاص استفاده کنید:

Mail::mailer('postmark')
        ->to($request->user())
        ->send(new OrderShipped($order));

نامه در صف

در صف یک پیام ایمیل

از آنجایی که ارسال پیام‌های ایمیل می‌تواند بر زمان پاسخ‌دهی برنامه شما تأثیر منفی بگذارد، بسیاری از توسعه‌دهندگان تصمیم می‌گیرند پیام‌های ایمیل را برای ارسال پس‌زمینه در صف قرار دهند. لاراول با استفاده از API صف یکپارچه داخلی خود این کار را آسان می کند . برای صف بندی یک پیام ایمیل، پس از مشخص کردن گیرندگان پیام، از queue روش روی نما استفاده کنید: Mail

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue(new OrderShipped($order));

این روش به طور خودکار از فشار دادن یک کار در صف مراقبت می کند تا پیام در پس زمینه ارسال شود. قبل از استفاده از این ویژگی باید صف های خود را پیکربندی کنید .

صف پیام با تاخیر

اگر می خواهید تحویل یک پیام ایمیل در صف را به تاخیر بیندازید، می توانید از این later روش استفاده کنید. متد به عنوان اولین آرگومان خود، نمونه ای later را می پذیرد DateTime که نشان می دهد چه زمانی پیام باید ارسال شود:

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->later(now()->addMinutes(10), new OrderShipped($order));

فشار دادن به صف های خاص

از آنجایی که همه کلاس‌های ارسال‌پذیر تولید شده با استفاده از make:mail دستور از این ویژگی استفاده می‌کنند Illuminate\Bus\Queueable ، می‌توانید متدهای onQueue و onConnection را در هر نمونه کلاس پستی فراخوانی کنید، که به شما امکان می‌دهد اتصال و نام صف پیام را مشخص کنید:

$message = (new OrderShipped($order))
                ->onConnection('sqs')
                ->onQueue('emails');
 
Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue($message);

صف به صورت پیش فرض

اگر کلاس‌های پستی دارید که می‌خواهید همیشه در صف باشند، می‌توانید ShouldQueue قرارداد را روی کلاس پیاده‌سازی کنید. اکنون، حتی اگر هنگام ارسال نامه، متد را فراخوانی کنید send ، mailable همچنان در صف قرار می گیرد زیرا قرارداد را اجرا می کند:

use Illuminate\Contracts\Queue\ShouldQueue;
 
class OrderShipped extends Mailable implements ShouldQueue
{
    //
}

تراکنش های پستی و پایگاه داده در صف

هنگامی که پست‌های صف‌بندی شده در تراکنش‌های پایگاه داده ارسال می‌شوند، ممکن است قبل از انجام تراکنش پایگاه داده توسط صف پردازش شوند. هنگامی که این اتفاق می افتد، هر به روز رسانی که در طول تراکنش پایگاه داده در مدل ها یا رکوردهای پایگاه داده انجام داده اید ممکن است هنوز در پایگاه داده منعکس نشود. علاوه بر این، هر مدل یا رکورد پایگاه داده ایجاد شده در تراکنش ممکن است در پایگاه داده وجود نداشته باشد. اگر mailable شما به این مدل‌ها بستگی دارد، خطاهای غیرمنتظره‌ای ممکن است هنگام پردازش کاری که پست‌پذیر در صف را ارسال می‌کند رخ دهد.

اگر گزینه پیکربندی اتصال صف شما after_commit روی تنظیم شده باشد false ، همچنان ممکن است با فراخوانی روش هنگام ارسال پیام ایمیل، نشان دهید که پس از انجام تمام تراکنش‌های پایگاه‌داده باز، یک afterCommit پستی در صف خاص باید ارسال شود:

Mail::to($request->user())->send(
    (new OrderShipped($order))->afterCommit()
);

از طرف دیگر، می توانید afterCommit متد را از سازنده mailable خود فراخوانی کنید:

<?php
 
namespace App\Mail;
 
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels;
 
    /**
     * Create a new message instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->afterCommit();
    }
}

برای کسب اطلاعات بیشتر در مورد کار در مورد این مسائل، لطفاً اسناد مربوط به مشاغل در صف و تراکنش های پایگاه داده را مرور کنید .

ارائه Mailables

گاهی اوقات ممکن است بخواهید محتوای HTML یک پستی را بدون ارسال آن ضبط کنید. برای انجام این کار، می توانید render روش mailable را فراخوانی کنید. این روش محتوای HTML ارزیابی شده پستی را به عنوان یک رشته برمی گرداند:

use App\Mail\InvoicePaid;
use App\Models\Invoice;
 
$invoice = Invoice::find(1);
 
return (new InvoicePaid($invoice))->render();

پیش نمایش ایمیل ها در مرورگر

هنگام طراحی یک الگوی پستی، آسان است که به سرعت پیش نمایش پستی ارائه شده در مرورگر خود را مانند یک الگوی معمولی Blade مشاهده کنید. به همین دلیل، لاراول به شما این امکان را می دهد که هر پستی را مستقیماً از بسته شدن مسیر یا کنترلر برگردانید. هنگامی که یک mailable برگردانده می شود، رندر می شود و در مرورگر نمایش داده می شود و به شما این امکان را می دهد که به سرعت طرح آن را بدون نیاز به ارسال آن به یک آدرس ایمیل واقعی پیش نمایش کنید:

Route::get('/mailable', function () {
    $invoice = App\Models\Invoice::find(1);
 
    return new App\Mail\InvoicePaid($invoice);
});

زمانی که یک فایل پستی در مرورگر شما پیش نمایش داده می شود، پیوست های درون خطی ارائه نمی شوند. برای پیش نمایش این فایل های پستی، باید آنها را به یک برنامه آزمایش ایمیل مانند MailHog یا HELO ارسال کنید .

بومی سازی Mailables

لاراول به شما این امکان را می‌دهد که فایل‌های پستی را در محلی غیر از محلی کنونی درخواست ارسال کنید و حتی اگر نامه‌ها در صف قرار بگیرند، این منطقه را به خاطر می‌آورند.

برای انجام این کار، نما روشی را برای تنظیم زبان مورد نظر Mail ارائه می دهد . locale هنگامی که الگوی پستی در حال ارزیابی است، برنامه به این منطقه تغییر می‌کند و پس از تکمیل ارزیابی، به محلی قبلی برمی‌گردد:

Mail::to($request->user())->locale('es')->send(
    new OrderShipped($order)
);

لوکال های برگزیده کاربر

گاهی اوقات، برنامه ها محلی مورد نظر هر کاربر را ذخیره می کنند. با اجرای HasLocalePreference قرارداد بر روی یک یا چند مدل خود، می توانید به لاراول دستور دهید که از این محلی ذخیره شده هنگام ارسال نامه استفاده کند:

use Illuminate\Contracts\Translation\HasLocalePreference;
 
class User extends Model implements HasLocalePreference
{
    /**
     * Get the user's preferred locale.
     *
     * @return string
     */
    public function preferredLocale()
    {
        return $this->locale;
    }
}

هنگامی که رابط را پیاده سازی کردید، لاراول به طور خودکار از محلی ترجیحی هنگام ارسال پستی و اعلان ها به مدل استفاده می کند. locale بنابراین، هنگام استفاده از این رابط، نیازی به فراخوانی متد نیست :

Mail::to($request->user())->send(new OrderShipped($order));

تست Mailables

لاراول چندین روش راحت را برای آزمایش اینکه پست‌های شما حاوی محتوای مورد انتظار شما هستند ارائه می‌کند. این روش ها عبارتند از: assertSeeInHtml , assertDontSeeInHtml , assertSeeInText , و assertDontSeeInText .

همانطور که ممکن است انتظار داشته باشید، اظهارات "HTML" بیان می کند که نسخه HTML پستی شما حاوی یک رشته معین است، در حالی که ادعاهای "متن" بیان می کنند که نسخه متنی ساده پستی شما حاوی یک رشته معین است:

use App\Mail\InvoicePaid;
use App\Models\User;
 
public function test_mailable_content()
{
    $user = User::factory()->create();
 
    $mailable = new InvoicePaid($user);
 
    $mailable->assertSeeInHtml($user->email);
    $mailable->assertSeeInHtml('Invoice Paid');
 
    $mailable->assertSeeInText($user->email);
    $mailable->assertSeeInText('Invoice Paid');
}

تست ارسال پستی

پیشنهاد می‌کنیم محتوای فایل‌های پستی خود را جدا از آزمایش‌هایی که ادعا می‌کنند یک پستی داده شده برای یک کاربر خاص "ارسال شده است" را آزمایش کنید. برای یادگیری نحوه آزمایش ارسال نامه‌های ارسالی، اسناد ما را در مورد Mail Fake بررسی کنید .

ایمیل و توسعه محلی

هنگام توسعه برنامه‌ای که ایمیل ارسال می‌کند، احتمالاً نمی‌خواهید ایمیل‌هایی را به آدرس‌های ایمیل زنده ارسال کنید. لاراول چندین راه برای "غیرفعال کردن" ارسال واقعی ایمیل ها در طول توسعه محلی ارائه می دهد.

درایور لاگ

به جای ارسال ایمیل‌های شما، log درایور ایمیل تمام پیام‌های ایمیل را برای بررسی در فایل‌های گزارش شما می‌نویسد. به طور معمول، این درایور فقط در طول توسعه محلی استفاده می شود. برای اطلاعات بیشتر در مورد پیکربندی برنامه خود در هر محیط، اسناد پیکربندی را بررسی کنید .

HELO / Mailtrap / MailHog

از طرف دیگر، می‌توانید از سرویسی مانند HELO یا Mailtrap و smtp درایور برای ارسال پیام‌های ایمیل خود به یک صندوق پستی ساختگی استفاده کنید، جایی که می‌توانید آنها را در یک سرویس گیرنده ایمیل واقعی مشاهده کنید. این رویکرد این مزیت را دارد که به شما امکان می‌دهد ایمیل‌های نهایی را در نمایشگر پیام Mailtrap بررسی کنید.

اگر از Laravel Sail استفاده می‌کنید ، می‌توانید پیام‌های خود را با استفاده از MailHog پیش‌نمایش کنید . هنگامی که Sail در حال اجرا است، می توانید به رابط MailHog در آدرس زیر دسترسی داشته باشید http://localhost:8025 .

to استفاده از یک آدرس جهانی

در نهایت، می توانید با فراخوانی alwaysTo روش ارائه شده توسط Mail نما، یک آدرس جهانی "to" را مشخص کنید. boot به طور معمول، این روش باید از روش یکی از ارائه دهندگان خدمات برنامه شما فراخوانی شود :

use Illuminate\Support\Facades\Mail;
 
/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    if ($this->app->environment('local')) {
        Mail::alwaysTo('taylor@example.com');
    }
}

مناسبت ها

لاراول در طول فرآیند ارسال پیام های ایمیلی دو رویداد را اجرا می کند. رویداد MessageSending قبل از ارسال پیام فعال می شود، در حالی که MessageSent رویداد پس از ارسال پیام فعال می شود. به یاد داشته باشید، این رویدادها هنگام ارسال نامه اجرا می شوند ، نه زمانی که در صف قرار می گیرند. می توانید شنوندگان رویداد را برای این رویداد در App\Providers\EventServiceProvider ارائه دهنده خدمات خود ثبت کنید:

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Mail\Events\MessageSending' => [
        'App\Listeners\LogSendingMessage',
    ],
    'Illuminate\Mail\Events\MessageSent' => [
        'App\Listeners\LogSentMessage',
    ],
];