ایمیل

• معرفی
  • پیکربندی
  • پیش نیاز راننده
  • پیکربندی Failover
  • پیکربندی دور رابین
• تولید Mailables
• نوشتن Mailables
  • پیکربندی فرستنده
  • پیکربندی View
  • مشاهده داده ها
  • پیوست ها
  • پیوست های درون خطی
  • اشیاء قابل اتصال
  • سرصفحه ها
  • برچسب ها و ابرداده ها
  • سفارشی کردن پیام Symfony
• Markdown Mailables
  • ایجاد Markdown Mailables
  • نوشتن پیام های علامت گذاری
  • سفارشی سازی کامپوننت ها
• ارسال نامه
  • نامه در صف
• ارائه Mailables
  • پیش نمایش Mailable ها در مرورگر
• بومی سازی Mailables
• آزمایش کردن
  • آزمایش محتوای پستی
  • تست ارسال پستی
• پست و توسعه محلی
• مناسبت ها
• حمل و نقل سفارشی
  • حمل و نقل Symfony اضافی

معرفی

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

پیکربندی

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

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

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

درایورهای مبتنی بر API مانند Mailgun، Postmark و MailerSend اغلب ساده‌تر و سریع‌تر از ارسال نامه از طریق سرورهای SMTP هستند. در صورت امکان، توصیه می کنیم از یکی از این درایورها استفاده کنید.

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

برای استفاده از درایور Mailgun، Symfony's Mailgun Mailer transport را از طریق Composer نصب کنید:

composer require symfony/mailgun-mailer symfony/http-client

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

'mailgun' => [
    'transport' => 'mailgun',
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

پس از پیکربندی ایمیل پیش فرض برنامه، گزینه های زیر را به config/services.php فایل پیکربندی خود اضافه کنید:

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

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

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

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

برای استفاده از درایور Postmark، Symfony's Postmark Mailer transport را از طریق Composer نصب کنید:

composer require symfony/postmark-mailer symfony/http-client

در مرحله بعد، گزینه موجود در فایل پیکربندی 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'),
    // 'client' => [
    //     'timeout' => 5,
    // ],
],

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

درایور 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'),
],

برای تعامل با ویژگی‌های مدیریت اشتراک SES ، می‌توانید X-Ses-List-Management-Options سرصفحه آرایه‌ای را که با headers روش پیام ایمیل بازگردانده شده است، برگردانید :

/**
 * Get the message headers.
 */
public function headers(): Headers
{
    return new Headers(
        text: [
            'X-Ses-List-Management-Options' => 'contactListName=MyContactList;topicName=MyTopic',
        ],
    );
}

اگر می خواهید گزینه های دیگری را SendEmail تعریف کنید که لاراول باید هنگام ارسال ایمیل به متد 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',
        'EmailTags' => [
            ['Name' => 'foo', 'Value' => 'bar'],
        ],
    ],
],

درایور MailerSend

MailerSend ، یک سرویس ایمیل و پیامک تراکنشی، درایور ایمیل مبتنی بر API خود را برای لاراول حفظ می کند. بسته حاوی درایور ممکن است از طریق مدیر بسته Composer نصب شود:

composer require mailersend/laravel-driver

پس از نصب بسته، MAILERSEND_API_KEY متغیر محیطی را به فایل برنامه خود اضافه کنید .env . علاوه بر این، MAIL_MAILER متغیر محیطی باید به صورت زیر تعریف شود mailersend :

MAIL_MAILER=mailersend
MAIL_FROM_ADDRESS=app@yourdomain.com
MAIL_FROM_NAME="App Name"
 
MAILERSEND_API_KEY=your-api-key

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

پیکربندی Failover

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

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

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

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

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

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

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

'mailers' => [
    'roundrobin' => [
        'transport' => 'roundrobin',
        'mailers' => [
            'ses',
            'postmark',
        ],
    ],
 
    // ...
],

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

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

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

تولید Mailables

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

php artisan make:mail OrderShipped

نوشتن Mailables

هنگامی که یک کلاس پستی ایجاد کردید، آن را باز کنید تا بتوانیم محتوای آن را بررسی کنیم. پیکربندی کلاس Mailable در چندین روش از جمله متدها envelope ، content و attachments متدها انجام می شود .

متد envelope یک Illuminate\Mail\Mailables\Envelope شی را برمی گرداند که موضوع و گاهی اوقات گیرندگان پیام را تعریف می کند. این content روش یک Illuminate\Mail\Mailables\Content شی را برمی گرداند که الگوی Blade را تعریف می کند که برای تولید محتوای پیام استفاده می شود.

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

با استفاده از پاکت نامه

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

use Illuminate\Mail\Mailables\Address;
use Illuminate\Mail\Mailables\Envelope;
 
/**
 * Get the message envelope.
 */
public function envelope(): Envelope
{
    return new Envelope(
        from: new Address('jeffrey@example.com', 'Jeffrey Way'),
        subject: 'Order Shipped',
    );
}

در صورت تمایل می توانید یک replyTo آدرس را نیز مشخص کنید:

return new Envelope(
    from: new Address('jeffrey@example.com', 'Jeffrey Way'),
    replyTo: [
        new Address('taylor@example.com', 'Taylor Otwell'),
    ],
    subject: 'Order Shipped',
);

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

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

'from' => [
    'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
    'name' => env('MAIL_FROM_NAME', 'Example'),
],

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

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

پیکربندی View

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

/**
 * Get the message content definition.
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
    );
}

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

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

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

/**
 * Get the message content definition.
 */
public function content(): Content
{
    return new Content(
        view: 'mail.orders.shipped',
        text: 'mail.orders.shipped-text'
    );
}

برای وضوح، html پارامتر ممکن است به عنوان نام مستعار پارامتر استفاده شود view :

return new Content(
    html: 'mail.orders.shipped',
    text: 'mail.orders.shipped-text'
);

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

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

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

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * Create a new message instance.
     */
    public function __construct(
        public Order $order,
    ) {}
 
    /**
     * Get the message content definition.
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
        );
    }
}

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

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

از طریق with پارامتر:

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

<?php
 
namespace App\Mail;
 
use App\Models\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Queue\SerializesModels;
 
class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;
 
    /**
     * Create a new message instance.
     */
    public function __construct(
        protected Order $order,
    ) {}
 
    /**
     * Get the message content definition.
     */
    public function content(): Content
    {
        return new Content(
            view: 'mail.orders.shipped',
            with: [
                'orderName' => $this->order->name,
                'orderPrice' => $this->order->price,
            ],
        );
    }
}

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

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

پیوست ها

برای افزودن پیوست‌ها به ایمیل، پیوست‌هایی را به آرایه‌ای که با روش پیام بازگردانده شده است اضافه می‌کنید attachments . ابتدا، می‌توانید با ارائه مسیر فایل به fromPath متد ارائه‌شده توسط Attachment کلاس، یک پیوست اضافه کنید:

use Illuminate\Mail\Mailables\Attachment;
 
/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file'),
    ];
}

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

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromPath('/path/to/file')
                ->as('name.pdf')
                ->withMime('application/pdf'),
    ];
}

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

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

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

البته، می‌توانید نام پیوست و نوع MIME را نیز مشخص کنید:

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file')
                ->as('name.pdf')
                ->withMime('application/pdf'),
    ];
}

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

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorageDisk('s3', '/path/to/file')
                ->as('name.pdf')
                ->withMime('application/pdf'),
    ];
}

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

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

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromData(fn () => $this->pdf, 'Report.pdf')
                ->withMime('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>

اشیاء قابل اتصال

در حالی که پیوست کردن فایل ها به پیام ها از طریق مسیرهای رشته ای ساده اغلب کافی است، در بسیاری از موارد موجودیت های قابل پیوست در برنامه شما با کلاس ها نشان داده می شوند. برای مثال، اگر برنامه شما عکسی را به پیامی پیوست می‌کند، ممکن است برنامه شما مدلی داشته باشد Photo که آن عکس را نشان می‌دهد. وقتی چنین است، آیا انتقال Photo مدل به روش راحت نیست attach ؟ اشیاء قابل اتصال به شما این امکان را می دهند که این کار را انجام دهید.

برای شروع، Illuminate\Contracts\Mail\Attachable اینترفیس را روی شیئی که به پیام‌ها متصل می‌شود، پیاده‌سازی کنید. این رابط دیکته می کند که کلاس شما toMailAttachment متدی را تعریف کند که یک Illuminate\Mail\Attachment نمونه را برمی گرداند:

<?php
 
namespace App\Models;
 
use Illuminate\Contracts\Mail\Attachable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Mail\Attachment;
 
class Photo extends Model implements Attachable
{
    /**
     * Get the attachable representation of the model.
     */
    public function toMailAttachment(): Attachment
    {
        return Attachment::fromPath('/path/to/file');
    }
}

هنگامی که شیء قابل پیوست خود را تعریف کردید، می توانید نمونه ای از آن شی را از attachments متد هنگام ساخت پیام ایمیل برگردانید:

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [$this->photo];
}

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

// Create an attachment from a file on your default disk...
return Attachment::fromStorage($this->path);
 
// Create an attachment from a file on a specific disk...
return Attachment::fromStorageDisk('backblaze', $this->path);

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

return Attachment::fromData(fn () => $this->content, 'Photo Name');

لاراول همچنین روش های دیگری را ارائه می دهد که می توانید از آنها برای سفارشی کردن پیوست های خود استفاده کنید. به عنوان مثال، می توانید از متدهای as و withMime برای سفارشی کردن نام فایل و نوع MIME استفاده کنید:

return Attachment::fromPath('/path/to/file')
        ->as('Photo Name')
        ->withMime('image/jpeg');

سرصفحه ها

گاهی اوقات ممکن است لازم باشد سرصفحه های اضافی را به پیام ارسالی پیوست کنید. به عنوان مثال، ممکن است لازم باشد یک Message-Id سرصفحه متن دلخواه یا سفارشی تنظیم کنید.

برای انجام این کار، headers روشی را روی mailable خود تعریف کنید. متد headers باید یک Illuminate\Mail\Mailables\Headers نمونه برگرداند. این کلاس messageId , references و text پارامترها را می پذیرد. البته، شما ممکن است فقط پارامترهایی را که برای پیام خاص خود نیاز دارید ارائه دهید:

use Illuminate\Mail\Mailables\Headers;
 
/**
 * Get the message headers.
 */
public function headers(): Headers
{
    return new Headers(
        messageId: 'custom-message-id@example.com',
        references: ['previous-message@example.com'],
        text: [
            'X-Custom-Header' => 'Custom Value',
        ],
    );
}

برچسب ها و ابرداده ها

برخی از ارائه‌دهندگان ایمیل شخص ثالث مانند Mailgun و Postmark از پیام‌های "برچسب‌ها" و "متاداده" پشتیبانی می‌کنند، که ممکن است برای گروه‌بندی و ردیابی ایمیل‌های ارسال شده توسط برنامه شما استفاده شوند. شما می توانید برچسب ها و ابرداده ها را از طریق تعریف خود به یک پیام ایمیل اضافه کنید Envelope :

use Illuminate\Mail\Mailables\Envelope;
 
/**
 * Get the message envelope.
 *
 * @return \Illuminate\Mail\Mailables\Envelope
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        tags: ['shipment'],
        metadata: [
            'order_id' => $this->order->id,
        ],
    );
}

اگر برنامه شما از درایور Mailgun استفاده می کند، می توانید برای اطلاعات بیشتر در مورد برچسب ها و ابرداده ها به اسناد Mailgun مراجعه کنید . به همین ترتیب، ممکن است برای اطلاعات بیشتر در مورد پشتیبانی آن‌ها از برچسب‌ها و ابرداده، از اسناد Postmark نیز استفاده شود .

اگر برنامه شما از آمازون SES برای ارسال ایمیل استفاده می کند، باید از metadata روشی برای پیوست کردن "برچسب ها" SES به پیام استفاده کنید.

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

قابلیت های ایمیل لاراول توسط Symfony Mailer ارائه می شود. لاراول به شما این امکان را می دهد که تماس های سفارشی را ثبت کنید که با نمونه پیام Symfony قبل از ارسال پیام فراخوانی می شوند. این به شما فرصتی می دهد تا پیام را قبل از ارسال عمیقاً شخصی سازی کنید. برای انجام این کار، یک using پارامتر در Envelope تعریف خود تعریف کنید:

use Illuminate\Mail\Mailables\Envelope;
use Symfony\Component\Mime\Email;
 
/**
 * Get the message envelope.
 */
public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Order Shipped',
        using: [
            function (Email $message) {
                // ...
            },
        ]
    );
}

Markdown Mailables

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

ایجاد Markdown Mailables

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

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

سپس، هنگام پیکربندی Content تعریف mailable در content متد آن، از markdown پارامتر به جای پارامتر استفاده کنید view :

use Illuminate\Mail\Mailables\Content;
 
/**
 * Get the message content definition.
 */
public function content(): Content
{
    return new Content(
        markdown: 'mail.orders.shipped',
        with: [
            'url' => $this->orderUrl,
        ],
    );
}

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

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

<x-mail::message>
# Order Shipped
 
Your order has been shipped!
 
<x-mail::button :url="$url">
View Order
</x-mail::button>
 
Thanks,<br>
{{ config('app.name') }}
</x-mail::message>

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

جزء دکمه

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

<x-mail::button :url="$url" color="success">
View Order
</x-mail::button>

جزء پنل

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

<x-mail::panel>
This is the panel content.
</x-mail::panel>

جزء جدول

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

<x-mail::table>
| Laravel       | Table         | Example  |
| ------------- |:-------------:| --------:|
| Col 2 is      | Centered      | $10      |
| Col 3 is      | Right-Aligned | $20      |
</x-mail::table>

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

شما می توانید تمام اجزای ایمیل 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\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
 
class OrderShipmentController extends Controller
{
    /**
     * Ship the given order.
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);
 
        // Ship the order...
 
        Mail::to($request->user())->send(new OrderShipped($order));
 
        return redirect('/orders');
    }
}

شما فقط محدود به تعیین گیرندگان "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.
     */
    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();

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

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

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

بومی سازی 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.
     */
    public function preferredLocale(): string
    {
        return $this->locale;
    }
}

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

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

آزمایش کردن

آزمایش محتوای پستی

لاراول روش های مختلفی را برای بررسی ساختار پستی شما ارائه می دهد. علاوه بر این، لاراول چندین روش راحت را برای آزمایش اینکه پستی شما حاوی محتوایی است که شما انتظار دارید ارائه می دهد. این روش ها عبارتند از: assertSeeInHtml , assertDontSeeInHtml , assertSeeInOrderInHtml , assertSeeInText , assertDontSeeInText , assertSeeInOrderInText , assertHasAttachment , assertHasAttachedData , assertHasAttachmentFromStorage , و assertHasAttachmentFromStorageDisk .

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

use App\Mail\InvoicePaid;
use App\Models\User;
 
test('mailable content', function () {
    $user = User::factory()->create();
 
    $mailable = new InvoicePaid($user);
 
    $mailable->assertFrom('jeffrey@example.com');
    $mailable->assertTo('taylor@example.com');
    $mailable->assertHasCc('abigail@example.com');
    $mailable->assertHasBcc('victoria@example.com');
    $mailable->assertHasReplyTo('tyler@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');
 
    $mailable->assertSeeInHtml($user->email);
    $mailable->assertSeeInHtml('Invoice Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);
 
    $mailable->assertSeeInText($user->email);
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);
 
    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
});

use App\Mail\InvoicePaid;
use App\Models\User;
 
public function test_mailable_content(): void
{
    $user = User::factory()->create();
 
    $mailable = new InvoicePaid($user);
 
    $mailable->assertFrom('jeffrey@example.com');
    $mailable->assertTo('taylor@example.com');
    $mailable->assertHasCc('abigail@example.com');
    $mailable->assertHasBcc('victoria@example.com');
    $mailable->assertHasReplyTo('tyler@example.com');
    $mailable->assertHasSubject('Invoice Paid');
    $mailable->assertHasTag('example-tag');
    $mailable->assertHasMetadata('key', 'value');
 
    $mailable->assertSeeInHtml($user->email);
    $mailable->assertSeeInHtml('Invoice Paid');
    $mailable->assertSeeInOrderInHtml(['Invoice Paid', 'Thanks']);
 
    $mailable->assertSeeInText($user->email);
    $mailable->assertSeeInOrderInText(['Invoice Paid', 'Thanks']);
 
    $mailable->assertHasAttachment('/path/to/file');
    $mailable->assertHasAttachment(Attachment::fromPath('/path/to/file'));
    $mailable->assertHasAttachedData($pdfData, 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorage('/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
    $mailable->assertHasAttachmentFromStorageDisk('s3', '/path/to/file', 'name.pdf', ['mime' => 'application/pdf']);
}

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

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

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

<?php
 
use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;
 
test('orders can be shipped', function () {
    Mail::fake();
 
    // Perform order shipping...
 
    // Assert that no mailables were sent...
    Mail::assertNothingSent();
 
    // Assert that a mailable was sent...
    Mail::assertSent(OrderShipped::class);
 
    // Assert a mailable was sent twice...
    Mail::assertSent(OrderShipped::class, 2);
 
    // Assert a mailable was not sent...
    Mail::assertNotSent(AnotherMailable::class);
 
    // Assert 3 total mailables were sent...
    Mail::assertSentCount(3);
});

<?php
 
namespace Tests\Feature;
 
use App\Mail\OrderShipped;
use Illuminate\Support\Facades\Mail;
use Tests\TestCase;
 
class ExampleTest extends TestCase
{
    public function test_orders_can_be_shipped(): void
    {
        Mail::fake();
 
        // Perform order shipping...
 
        // Assert that no mailables were sent...
        Mail::assertNothingSent();
 
        // Assert that a mailable was sent...
        Mail::assertSent(OrderShipped::class);
 
        // Assert a mailable was sent twice...
        Mail::assertSent(OrderShipped::class, 2);
 
        // Assert a mailable was not sent...
        Mail::assertNotSent(AnotherMailable::class);
 
        // Assert 3 total mailables were sent...
        Mail::assertSentCount(3);
    }
}

اگر پست‌های پستی را برای تحویل در پس‌زمینه در صف قرار می‌دهید، باید از assertQueued روش به جای استفاده از assertSent :

Mail::assertQueued(OrderShipped::class);
Mail::assertNotQueued(OrderShipped::class);
Mail::assertNothingQueued();
Mail::assertQueuedCount(3);

می‌توانید روش‌های assertSent , assertNotSent , assertQueued , یا بسته شدن را بگذرانید assertNotQueued تا ادعا کنید که یک پستی ارسال شده است که یک "تست حقیقت" معین را گذرانده است. اگر حداقل یک پستی ارسال شده باشد که آزمون صدق داده شده را با موفقیت پشت سر بگذارد، ادعا موفقیت آمیز خواهد بود:

Mail::assertSent(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

هنگام فراخوانی Mail روش‌های ادعای نما، نمونه پستی پذیرفته شده توسط بسته ارائه شده، روش‌های مفیدی را برای بررسی قابل ارسال نشان می‌دهد:

Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($user) {
    return $mail->hasTo($user->email) &&
           $mail->hasCc('...') &&
           $mail->hasBcc('...') &&
           $mail->hasReplyTo('...') &&
           $mail->hasFrom('...') &&
           $mail->hasSubject('...');
});

نمونه mailable همچنین شامل چندین روش مفید برای بررسی پیوست‌های موجود در یک mailable است:

use Illuminate\Mail\Mailables\Attachment;
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromPath('/path/to/file')
                ->as('name.pdf')
                ->withMime('application/pdf')
    );
});
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
    return $mail->hasAttachment(
        Attachment::fromStorageDisk('s3', '/path/to/file')
    );
});
 
Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($pdfData) {
    return $mail->hasAttachment(
        Attachment::fromData(fn () => $pdfData, 'name.pdf')
    );
});

ممکن است متوجه شده باشید که دو روش برای اثبات عدم ارسال نامه وجود دارد: assertNotSent و assertNotQueued . گاهی اوقات ممکن است بخواهید ادعا کنید که هیچ نامه ای ارسال نشده یا در صف قرار نگرفته است. برای انجام این کار، می توانید از assertNothingOutgoing و assertNotOutgoing روش های زیر استفاده کنید:

Mail::assertNothingOutgoing();
 
Mail::assertNotOutgoing(function (OrderShipped $mail) use ($order) {
    return $mail->order->id === $order->id;
});

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

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

درایور لاگ

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

HELO / Mailtrap / Mailpit

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

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

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

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

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

مناسبت ها

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

use Illuminate\Mail\Events\MessageSending;
// use Illuminate\Mail\Events\MessageSent;
 
class LogMessage
{
    /**
     * Handle the given event.
     */
    public function handle(MessageSending $event): void
    {
        // ...
    }
}

حمل و نقل سفارشی

لاراول شامل انواع حمل و نقل نامه است. با این حال، ممکن است بخواهید برای ارسال ایمیل از طریق سرویس‌های دیگری که لاراول از آنها پشتیبانی نمی‌کند، پیام‌های انتقال خود را بنویسید. برای شروع، کلاسی را تعریف کنید که Symfony\Component\Mailer\Transport\AbstractTransport کلاس را گسترش دهد. سپس، doSend و __toString() روش ها را در حمل و نقل خود پیاده کنید:

use MailchimpTransactional\ApiClient;
use Symfony\Component\Mailer\SentMessage;
use Symfony\Component\Mailer\Transport\AbstractTransport;
use Symfony\Component\Mime\Address;
use Symfony\Component\Mime\MessageConverter;
 
class MailchimpTransport extends AbstractTransport
{
    /**
     * Create a new Mailchimp transport instance.
     */
    public function __construct(
        protected ApiClient $client,
    ) {
        parent::__construct();
    }
 
    /**
     * {@inheritDoc}
     */
    protected function doSend(SentMessage $message): void
    {
        $email = MessageConverter::toEmail($message->getOriginalMessage());
 
        $this->client->messages->send(['message' => [
            'from_email' => $email->getFrom(),
            'to' => collect($email->getTo())->map(function (Address $email) {
                return ['email' => $email->getAddress(), 'type' => 'to'];
            })->all(),
            'subject' => $email->getSubject(),
            'text' => $email->getTextBody(),
        ]]);
    }
 
    /**
     * Get the string representation of the transport.
     */
    public function __toString(): string
    {
        return 'mailchimp';
    }
}

هنگامی که حمل و نقل سفارشی خود را تعریف کردید، می توانید آن را از طریق extend روش ارائه شده توسط Mail نما ثبت کنید. به طور معمول، این باید با boot روش ارائه دهنده خدمات برنامه شما انجام شود AppServiceProvider . یک $config آرگومان به بسته شدن ارائه شده به extend روش منتقل می شود. این آرگومان حاوی آرایه پیکربندی تعریف شده برای میلر در config/mail.php فایل پیکربندی برنامه است:

use App\Mail\MailchimpTransport;
use Illuminate\Support\Facades\Mail;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Mail::extend('mailchimp', function (array $config = []) {
        return new MailchimpTransport(/* ... */);
    });
}

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

'mailchimp' => [
    'transport' => 'mailchimp',
    // ...
],

حمل و نقل Symfony اضافی

لاراول شامل پشتیبانی از برخی از حمل و نقل نامه های موجود Symfony مانند Mailgun و Postmark است. با این حال، ممکن است بخواهید لاراول را با پشتیبانی از حمل و نقل های اضافی Symfony گسترش دهید. می توانید این کار را با درخواست ایمیل Symfony لازم از طریق Composer و ثبت حمل و نقل در لاراول انجام دهید. برای مثال، می‌توانید ایمیل Symfony را نصب و ثبت کنید:

composer require symfony/brevo-mailer symfony/http-client

پس از نصب بسته پست الکترونیکی Brevo، می توانید یک ورودی برای اعتبارنامه API Brevo خود به services فایل پیکربندی برنامه خود اضافه کنید:

'brevo' => [
    'key' => 'your-api-key',
],

در مرحله بعد، می توانید از روش Mail نما extend برای ثبت حمل و نقل با لاراول استفاده کنید. به طور معمول، این باید در boot روش ارائه دهنده خدمات انجام شود :

use Illuminate\Support\Facades\Mail;
use Symfony\Component\Mailer\Bridge\Brevo\Transport\BrevoTransportFactory;
use Symfony\Component\Mailer\Transport\Dsn;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Mail::extend('brevo', function () {
        return (new BrevoTransportFactory)->create(
            new Dsn(
                'brevo+api',
                'default',
                config('services.brevo.key')
            )
        );
    });
}

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

'brevo' => [
    'transport' => 'brevo',
    // ...
],