Mailable.php
TLDR
The Mailable.php file is a class in the Illuminate\Mail namespace that extends the MailableContract and Renderable interfaces. This class represents an email message and provides methods for setting up the details of the message such as the sender, recipients, subject, and attachments. It also provides methods for sending and queueing the message.
Methods
There are several methods defined in the Mailable class:
send($mailer)
This method sends the message using the given mailer. It builds the view and view data for the message, then calls the send method on the mailer instance, passing in the view, view data, and a callback that builds the message.
queue($queue)
This method queues the message for sending. It checks if the delay property is set, and if so, schedules the message to be sent after a delay. Otherwise, it retrieves the connection and queue properties (if they exist), and pushes the message onto the specified queue using the queue connection.
later($delay, $queue)
This method delivers the queued message after a specified delay. It takes a delay time (in seconds, a DateTimeInterface, or a DateInterval), a queue instance, and schedules the message to be sent after the delay on the specified queue connection.
newQueuedJob()
This method creates a new instance of the queued mailable job.
render()
This method renders the mailable into a view. It prepares the mailable for delivery, then calls the render method on the mailer instance, passing in the view and view data.
buildView()
This method builds the view for the message. It checks if the html property is set, and if so, returns an array with the HTML and text versions of the content. If the markdown property is set, it calls the buildMarkdownView method to build the Markdown view. If both the view and textView properties are set, it returns an array with the view and text view. Otherwise, it returns the view property.
buildMarkdownView()
This method builds the Markdown view for the message. It builds the view data and returns an array with the HTML and text versions of the content.
buildViewData()
This method builds the view data for the message. It merges the viewData property with the result of a viewDataCallback (if set) and the public properties of the mailable. It uses reflection to get the public properties of the mailable class, excluding properties inherited from the Mailable class itself.
buildMarkdownHtml($viewData)
This method builds the HTML view for a Markdown message. It returns a closure that takes a data array and renders the Markdown view using the markdownRenderer method.
buildMarkdownText($viewData)
This method builds the text view for a Markdown message. It returns a closure that takes a data array and renders the Markdown text using the markdownRenderer method.
markdownRenderer()
This method resolves a Markdown instance with the mail's theme. It creates a new instance of the Markdown class, sets the theme based on the theme property (or a default value), and returns the instance.
buildFrom($message)
This method adds the sender to the message. It checks if the from property is not empty and calls the from method on the message instance, passing in the first address and name from the from property.
buildRecipients($message)
This method adds all of the recipients to the message. It loops through the to, cc, bcc, and replyTo properties and calls the corresponding method on the message instance for each recipient.
buildSubject($message)
This method sets the subject for the message. If the subject property is set, it calls the subject method on the message instance with the value of the subject property. Otherwise, it generates a default subject based on the mailable class name.
buildAttachments($message)
This method adds all of the attachments to the message. It loops through the attachments and rawAttachments properties and calls the corresponding methods on the message instance to attach the files.
buildDiskAttachments($message)
This method adds all of the disk attachments to the message. It loops through the diskAttachments property and reads the files from the storage disks, then uses the attachData method on the message instance to attach the files.
buildTags($message)
This method adds all defined tags to the message. It loops through the tags property and adds each tag as a header to the message.
buildMetadata($message)
This method adds all defined metadata to the message. It loops through the metadata property and adds each metadata to the message as a header.
runCallbacks($message)
This method runs the callbacks for the message. It loops through the callbacks property and calls each callback, passing in the Symfony message instance.
locale($locale)
This method sets the locale of the message.
priority($level)
This method sets the priority of the message. It takes a level (an integer) and adds a callback that sets the priority header to the message.
from($address, $name = null)
This method sets the sender of the message. It takes an address and an optional name parameter and uses the setAddress method to add the sender to the from property.
hasFrom($address, $name = null)
This method checks if the given sender is set on the mailable.
to($address, $name = null)
This method sets the recipients of the message. It takes an address and an optional name parameter and uses the setAddress method to add the recipients to the to property.
hasTo($address, $name = null)
This method checks if the given recipient is set on the mailable.
cc($address, $name = null)
This method sets the "cc" recipients of the message. It takes an address and an optional name parameter and uses the setAddress method to add the recipients to the cc property.
hasCc($address, $name = null)
This method checks if the given recipient is set on the mailable.
bcc($address, $name = null)
This method sets the "bcc" recipients of the message. It takes an address and an optional name parameter and uses the setAddress method to add the recipients to the bcc property.
hasBcc($address, $name = null)
This method checks if the given recipient is set on the mailable.
replyTo($address, $name = null)
This method sets the "reply to" recipients of the message. It takes an address and an optional name parameter and uses the setAddress method to add the recipients to the replyTo property.
hasReplyTo($address, $name = null)
This method checks if the given recipient is set on the mailable.
setAddress($address, $name = null, $property = 'to')
This method sets the recipients of the message. It takes an address, an optional name parameter, and a property name (defaulting to "to") and adds the recipients to the specified property.
addressesToArray($address, $name)
This method converts the given recipient arguments to an array.
normalizeRecipient($recipient)
This method converts the given recipient into an object.
hasRecipient($address, $name = null, $property = 'to')
This method checks if the given recipient is set on the mailable.
hasEnvelopeRecipient($address, $name, $property)
This method checks if the mailable "envelope" method defines a recipient.
subject($subject)
This method sets the subject of the message.
hasSubject($subject)
This method checks if the mailable has the given subject.
markdown($view, $data = [])
This method sets the Markdown template for the message.
view($view, $data = [])
This method sets the view and view data for the message.
html($html)
This method sets the rendered HTML content for the message.
text($textView, $data = [])
This method sets the plain text view for the message.
with($key, $value = null)
This method sets the view data for the message. It takes a key and a value, or an array of key-value pairs.
attach($file, $options = [])
This method attaches a file to the message. It takes a file path or an instance of Attachable or Attachment, and optional options for the attachment. It adds the attachment to the attachments property.
attachMany($files)
This method attaches multiple files to the message. It takes an array of files and options, and calls the attach method for each file.
hasAttachment($file, $options = [])
This method checks if the mailable has the given attachment.
attachFromStorage($path, $name = null, $options = [])
This method attaches a file from storage to the message. It takes a file path, an optional name, and options for the attachment. It adds the attachment to the diskAttachments property.
attachFromStorageDisk($disk, $path, $name = null, $options = [])
This method attaches a file from storage with a specific disk to the message. It takes a disk name, a file path, an optional name, and options for the attachment. It adds the attachment to the diskAttachments property.
hasAttachmentFromStorage($path, $name = null, $options = [])
This method checks if the mailable has the given attachment from storage.
hasAttachmentFromStorageDisk($disk, $path, $name = null, $options = [])
This method checks if the mailable has the given attachment from a specific storage disk.
attachData($data, $name, $options = [])
This method attaches in-memory data as an attachment. It takes the data, a name, and options for the attachment. It adds the attachment to the rawAttachments property.
hasAttachedData($data, $name, $options = [])
This method checks if the mailable has the given data as an attachment.
tag($value)
This method adds a tag header to the message.
hasTag($value)
This method checks if the mailable has the given tag.
metadata($key, $value)
This method adds a metadata header to the message.
hasMetadata($key, $value)
This method checks if the mailable has the given metadata.
assertFrom($address, $name = null)
This method asserts that the mailable is from the given address.
assertTo($address, $name = null)
This method asserts that the mailable has the given recipient.
assertHasTo($address, $name = null)
This method asserts that the mailable has the given recipient.
assertHasCc($address, $name = null)
This method asserts that the mailable has the given recipient.
assertHasBcc($address, $name = null)
This method asserts that the mailable has the given recipient.
assertHasReplyTo($address, $name = null)
This method asserts that the mailable has the given "reply to" address.
assertHasSubject($subject)
This method asserts that the mailable has the given subject.
assertSeeInHtml($string, $escape = true)
This method asserts that the given text is present in the HTML email body.
assertDontSeeInHtml($string, $escape = true)
This method asserts that the given text is not present in the HTML email body.
assertSeeInOrderInHtml($strings, $escape = true)
This method asserts that the given text strings are present in order in the HTML email body.
assertSeeInText($string)
This method asserts that the given text is present in the plain-text email body.
assertDontSeeInText($string)
This method asserts that the given text is not present in the plain-text email body.
assertSeeInOrderInText($strings)
This method asserts that the given text strings are present in order in the plain-text email body.
assertHasAttachment($file, $options = [])
This method asserts that the mailable has the given attachment.
assertHasAttachedData($data, $name, $options = [])
This method asserts that the mailable has the given data as an attachment.
assertHasAttachmentFromStorage($path, $name = null, $options = [])
This method asserts that the mailable has the given attachment from storage.
assertHasAttachmentFromStorageDisk($disk, $path, $name = null, $options = [])
This method asserts that the mailable has the given attachment from a specific storage disk.
assertHasTag($tag)
This method asserts that the mailable has the given tag.
assertHasMetadata($key, $value)
This method asserts that the mailable has the given metadata.
Classes
There are no additional classes defined in the file.
<?php
namespace Illuminate\Mail;
use Illuminate\Config\Repository as ConfigRepository;
use Illuminate\Container\Container;
use Illuminate\Contracts\Filesystem\Factory as FilesystemFactory;
use Illuminate\Contracts\Mail\Attachable;
use Illuminate\Contracts\Mail\Factory as MailFactory;
use Illuminate\Contracts\Mail\Mailable as MailableContract;
use Illuminate\Contracts\Queue\Factory as Queue;
use Illuminate\Contracts\Support\Htmlable;
use Illuminate\Contracts\Support\Renderable;
use Illuminate\Contracts\Translation\HasLocalePreference;
use Illuminate\Support\Collection;
use Illuminate\Support\HtmlString;
use Illuminate\Support\Str;
use Illuminate\Support\Traits\Conditionable;
use Illuminate\Support\Traits\ForwardsCalls;
use Illuminate\Support\Traits\Localizable;
use Illuminate\Support\Traits\Macroable;
use Illuminate\Testing\Constraints\SeeInOrder;
use PHPUnit\Framework\Assert as PHPUnit;
use ReflectionClass;
use ReflectionProperty;
use Symfony\Component\Mailer\Header\MetadataHeader;
use Symfony\Component\Mailer\Header\TagHeader;
use Symfony\Component\Mime\Address;
class Mailable implements MailableContract, Renderable
{
use Conditionable, ForwardsCalls, Localizable, Macroable {
__call as macroCall;
}
/**
* The locale of the message.
*
* @var string
*/
public $locale;
/**
* The person the message is from.
*
* @var array
*/
public $from = [];
/**
* The "to" recipients of the message.
*
* @var array
*/
public $to = [];
/**
* The "cc" recipients of the message.
*
* @var array
*/
public $cc = [];
/**
* The "bcc" recipients of the message.
*
* @var array
*/
public $bcc = [];
/**
* The "reply to" recipients of the message.
*
* @var array
*/
public $replyTo = [];
/**
* The subject of the message.
*
* @var string
*/
public $subject;
/**
* The Markdown template for the message (if applicable).
*
* @var string
*/
public $markdown;
/**
* The HTML to use for the message.
*
* @var string
*/
protected $html;
/**
* The view to use for the message.
*
* @var string
*/
public $view;
/**
* The plain text view to use for the message.
*
* @var string
*/
public $textView;
/**
* The view data for the message.
*
* @var array
*/
public $viewData = [];
/**
* The attachments for the message.
*
* @var array
*/
public $attachments = [];
/**
* The raw attachments for the message.
*
* @var array
*/
public $rawAttachments = [];
/**
* The attachments from a storage disk.
*
* @var array
*/
public $diskAttachments = [];
/**
* The tags for the message.
*
* @var array
*/
protected $tags = [];
/**
* The metadata for the message.
*
* @var array
*/
protected $metadata = [];
/**
* The callbacks for the message.
*
* @var array
*/
public $callbacks = [];
/**
* The name of the theme that should be used when formatting the message.
*
* @var string|null
*/
public $theme;
/**
* The name of the mailer that should send the message.
*
* @var string
*/
public $mailer;
/**
* The rendered mailable views for testing / assertions.
*
* @var array
*/
protected $assertionableRenderStrings;
/**
* The callback that should be invoked while building the view data.
*
* @var callable
*/
public static $viewDataCallback;
/**
* Send the message using the given mailer.
*
* @param \Illuminate\Contracts\Mail\Factory|\Illuminate\Contracts\Mail\Mailer $mailer
* @return \Illuminate\Mail\SentMessage|null
*/
public function send($mailer)
{
return $this->withLocale($this->locale, function () use ($mailer) {
$this->prepareMailableForDelivery();
$mailer = $mailer instanceof MailFactory
? $mailer->mailer($this->mailer)
: $mailer;
return $mailer->send($this->buildView(), $this->buildViewData(), function ($message) {
$this->buildFrom($message)
->buildRecipients($message)
->buildSubject($message)
->buildTags($message)
->buildMetadata($message)
->runCallbacks($message)
->buildAttachments($message);
});
});
}
/**
* Queue the message for sending.
*
* @param \Illuminate\Contracts\Queue\Factory $queue
* @return mixed
*/
public function queue(Queue $queue)
{
if (isset($this->delay)) {
return $this->later($this->delay, $queue);
}
$connection = property_exists($this, 'connection') ? $this->connection : null;
$queueName = property_exists($this, 'queue') ? $this->queue : null;
return $queue->connection($connection)->pushOn(
$queueName ?: null, $this->newQueuedJob()
);
}
/**
* Deliver the queued message after (n) seconds.
*
* @param \DateTimeInterface|\DateInterval|int $delay
* @param \Illuminate\Contracts\Queue\Factory $queue
* @return mixed
*/
public function later($delay, Queue $queue)
{
$connection = property_exists($this, 'connection') ? $this->connection : null;
$queueName = property_exists($this, 'queue') ? $this->queue : null;
return $queue->connection($connection)->laterOn(
$queueName ?: null, $delay, $this->newQueuedJob()
);
}
/**
* Make the queued mailable job instance.
*
* @return mixed
*/
protected function newQueuedJob()
{
return Container::getInstance()->make(SendQueuedMailable::class, ['mailable' => $this])
->through(array_merge(
method_exists($this, 'middleware') ? $this->middleware() : [],
$this->middleware ?? []
));
}
/**
* Render the mailable into a view.
*
* @return string
*
* @throws \ReflectionException
*/
public function render()
{
return $this->withLocale($this->locale, function () {
$this->prepareMailableForDelivery();
return Container::getInstance()->make('mailer')->render(
$this->buildView(), $this->buildViewData()
);
});
}
/**
* Build the view for the message.
*
* @return array|string
*
* @throws \ReflectionException
*/
protected function buildView()
{
if (isset($this->html)) {
return array_filter([
'html' => new HtmlString($this->html),
'text' => $this->textView ?? null,
]);
}
if (isset($this->markdown)) {
return $this->buildMarkdownView();
}
if (isset($this->view, $this->textView)) {
return [$this->view, $this->textView];
} elseif (isset($this->textView)) {
return ['text' => $this->textView];
}
return $this->view;
}
/**
* Build the Markdown view for the message.
*
* @return array
*
* @throws \ReflectionException
*/
protected function buildMarkdownView()
{
$data = $this->buildViewData();
return [
'html' => $this->buildMarkdownHtml($data),
'text' => $this->buildMarkdownText($data),
];
}
/**
* Build the view data for the message.
*
* @return array
*
* @throws \ReflectionException
*/
public function buildViewData()
{
$data = $this->viewData;
if (static::$viewDataCallback) {
$data = array_merge($data, call_user_func(static::$viewDataCallback, $this));
}
foreach ((new ReflectionClass($this))->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
if ($property->getDeclaringClass()->getName() !== self::class) {
$data[$property->getName()] = $property->getValue($this);
}
}
return $data;
}
/**
* Build the HTML view for a Markdown message.
*
* @param array $viewData
* @return \Closure
*/
protected function buildMarkdownHtml($viewData)
{
return fn ($data) => $this->markdownRenderer()->render(
$this->markdown,
array_merge($data, $viewData),
);
}
/**
* Build the text view for a Markdown message.
*
* @param array $viewData
* @return \Closure
*/
protected function buildMarkdownText($viewData)
{
return function ($data) use ($viewData) {
if (isset($data['message'])) {
$data = array_merge($data, [
'message' => new TextMessage($data['message']),
]);
}
return $this->textView ?? $this->markdownRenderer()->renderText(
$this->markdown,
array_merge($data, $viewData)
);
};
}
/**
* Resolves a Markdown instance with the mail's theme.
*
* @return \Illuminate\Mail\Markdown
*/
protected function markdownRenderer()
{
return tap(Container::getInstance()->make(Markdown::class), function ($markdown) {
$markdown->theme($this->theme ?: Container::getInstance()->get(ConfigRepository::class)->get(
'mail.markdown.theme', 'default')
);
});
}
/**
* Add the sender to the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildFrom($message)
{
if (! empty($this->from)) {
$message->from($this->from[0]['address'], $this->from[0]['name']);
}
return $this;
}
/**
* Add all of the recipients to the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildRecipients($message)
{
foreach (['to', 'cc', 'bcc', 'replyTo'] as $type) {
foreach ($this->{$type} as $recipient) {
$message->{$type}($recipient['address'], $recipient['name']);
}
}
return $this;
}
/**
* Set the subject for the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildSubject($message)
{
if ($this->subject) {
$message->subject($this->subject);
} else {
$message->subject(Str::title(Str::snake(class_basename($this), ' ')));
}
return $this;
}
/**
* Add all of the attachments to the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildAttachments($message)
{
foreach ($this->attachments as $attachment) {
$message->attach($attachment['file'], $attachment['options']);
}
foreach ($this->rawAttachments as $attachment) {
$message->attachData(
$attachment['data'], $attachment['name'], $attachment['options']
);
}
$this->buildDiskAttachments($message);
return $this;
}
/**
* Add all of the disk attachments to the message.
*
* @param \Illuminate\Mail\Message $message
* @return void
*/
protected function buildDiskAttachments($message)
{
foreach ($this->diskAttachments as $attachment) {
$storage = Container::getInstance()->make(
FilesystemFactory::class
)->disk($attachment['disk']);
$message->attachData(
$storage->get($attachment['path']),
$attachment['name'] ?? basename($attachment['path']),
array_merge(['mime' => $storage->mimeType($attachment['path'])], $attachment['options'])
);
}
}
/**
* Add all defined tags to the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildTags($message)
{
if ($this->tags) {
foreach ($this->tags as $tag) {
$message->getHeaders()->add(new TagHeader($tag));
}
}
return $this;
}
/**
* Add all defined metadata to the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function buildMetadata($message)
{
if ($this->metadata) {
foreach ($this->metadata as $key => $value) {
$message->getHeaders()->add(new MetadataHeader($key, $value));
}
}
return $this;
}
/**
* Run the callbacks for the message.
*
* @param \Illuminate\Mail\Message $message
* @return $this
*/
protected function runCallbacks($message)
{
foreach ($this->callbacks as $callback) {
$callback($message->getSymfonyMessage());
}
return $this;
}
/**
* Set the locale of the message.
*
* @param string $locale
* @return $this
*/
public function locale($locale)
{
$this->locale = $locale;
return $this;
}
/**
* Set the priority of this message.
*
* The value is an integer where 1 is the highest priority and 5 is the lowest.
*
* @param int $level
* @return $this
*/
public function priority($level = 3)
{
$this->callbacks[] = function ($message) use ($level) {
$message->priority($level);
};
return $this;
}
/**
* Set the sender of the message.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function from($address, $name = null)
{
return $this->setAddress($address, $name, 'from');
}
/**
* Determine if the given recipient is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @return bool
*/
public function hasFrom($address, $name = null)
{
return $this->hasRecipient($address, $name, 'from');
}
/**
* Set the recipients of the message.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function to($address, $name = null)
{
if (! $this->locale && $address instanceof HasLocalePreference) {
$this->locale($address->preferredLocale());
}
return $this->setAddress($address, $name, 'to');
}
/**
* Determine if the given recipient is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @return bool
*/
public function hasTo($address, $name = null)
{
return $this->hasRecipient($address, $name, 'to');
}
/**
* Set the recipients of the message.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function cc($address, $name = null)
{
return $this->setAddress($address, $name, 'cc');
}
/**
* Determine if the given recipient is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @return bool
*/
public function hasCc($address, $name = null)
{
return $this->hasRecipient($address, $name, 'cc');
}
/**
* Set the recipients of the message.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function bcc($address, $name = null)
{
return $this->setAddress($address, $name, 'bcc');
}
/**
* Determine if the given recipient is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @return bool
*/
public function hasBcc($address, $name = null)
{
return $this->hasRecipient($address, $name, 'bcc');
}
/**
* Set the "reply to" address of the message.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function replyTo($address, $name = null)
{
return $this->setAddress($address, $name, 'replyTo');
}
/**
* Determine if the given replyTo is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @return bool
*/
public function hasReplyTo($address, $name = null)
{
return $this->hasRecipient($address, $name, 'replyTo');
}
/**
* Set the recipients of the message.
*
* All recipients are stored internally as [['name' => ?, 'address' => ?]]
*
* @param object|array|string $address
* @param string|null $name
* @param string $property
* @return $this
*/
protected function setAddress($address, $name = null, $property = 'to')
{
if (empty($address)) {
return $this;
}
foreach ($this->addressesToArray($address, $name) as $recipient) {
$recipient = $this->normalizeRecipient($recipient);
$this->{$property}[] = [
'name' => $recipient->name ?? null,
'address' => $recipient->email,
];
}
$this->{$property} = collect($this->{$property})
->reverse()
->unique('address')
->reverse()
->values()
->all();
return $this;
}
/**
* Convert the given recipient arguments to an array.
*
* @param object|array|string $address
* @param string|null $name
* @return array
*/
protected function addressesToArray($address, $name)
{
if (! is_array($address) && ! $address instanceof Collection) {
$address = is_string($name) ? [['name' => $name, 'email' => $address]] : [$address];
}
return $address;
}
/**
* Convert the given recipient into an object.
*
* @param mixed $recipient
* @return object
*/
protected function normalizeRecipient($recipient)
{
if (is_array($recipient)) {
if (array_values($recipient) === $recipient) {
return (object) array_map(function ($email) {
return compact('email');
}, $recipient);
}
return (object) $recipient;
} elseif (is_string($recipient)) {
return (object) ['email' => $recipient];
} elseif ($recipient instanceof Address) {
return (object) ['email' => $recipient->getAddress(), 'name' => $recipient->getName()];
} elseif ($recipient instanceof Mailables\Address) {
return (object) ['email' => $recipient->address, 'name' => $recipient->name];
}
return $recipient;
}
/**
* Determine if the given recipient is set on the mailable.
*
* @param object|array|string $address
* @param string|null $name
* @param string $property
* @return bool
*/
protected function hasRecipient($address, $name = null, $property = 'to')
{
if (empty($address)) {
return false;
}
$expected = $this->normalizeRecipient(
$this->addressesToArray($address, $name)[0]
);
$expected = [
'name' => $expected->name ?? null,
'address' => $expected->email,
];
if ($this->hasEnvelopeRecipient($expected['address'], $expected['name'], $property)) {
return true;
}
return collect($this->{$property})->contains(function ($actual) use ($expected) {
if (! isset($expected['name'])) {
return $actual['address'] == $expected['address'];
}
return $actual == $expected;
});
}
/**
* Determine if the mailable "envelope" method defines a recipient.
*
* @param string $address
* @param string|null $name
* @param string $property
* @return bool
*/
private function hasEnvelopeRecipient($address, $name, $property)
{
return method_exists($this, 'envelope') && match ($property) {
'from' => $this->envelope()->isFrom($address, $name),
'to' => $this->envelope()->hasTo($address, $name),
'cc' => $this->envelope()->hasCc($address, $name),
'bcc' => $this->envelope()->hasBcc($address, $name),
'replyTo' => $this->envelope()->hasReplyTo($address, $name),
};
}
/**
* Set the subject of the message.
*
* @param string $subject
* @return $this
*/
public function subject($subject)
{
$this->subject = $subject;
return $this;
}
/**
* Determine if the mailable has the given subject.
*
* @param string $subject
* @return bool
*/
public function hasSubject($subject)
{
return $this->subject === $subject ||
(method_exists($this, 'envelope') && $this->envelope()->hasSubject($subject));
}
/**
* Set the Markdown template for the message.
*
* @param string $view
* @param array $data
* @return $this
*/
public function markdown($view, array $data = [])
{
$this->markdown = $view;
$this->viewData = array_merge($this->viewData, $data);
return $this;
}
/**
* Set the view and view data for the message.
*
* @param string $view
* @param array $data
* @return $this
*/
public function view($view, array $data = [])
{
$this->view = $view;
$this->viewData = array_merge($this->viewData, $data);
return $this;
}
/**
* Set the rendered HTML content for the message.
*
* @param string $html
* @return $this
*/
public function html($html)
{
$this->html = $html;
return $this;
}
/**
* Set the plain text view for the message.
*
* @param string $textView
* @param array $data
* @return $this
*/
public function text($textView, array $data = [])
{
$this->textView = $textView;
$this->viewData = array_merge($this->viewData, $data);
return $this;
}
/**
* Set the view data for the message.
*
* @param string|array $key
* @param mixed $value
* @return $this
*/
public function with($key, $value = null)
{
if (is_array($key)) {
$this->viewData = array_merge($this->viewData, $key);
} else {
$this->viewData[$key] = $value;
}
return $this;
}
/**
* Attach a file to the message.
*
* @param string|\Illuminate\Contracts\Mail\Attachable|\Illuminate\Mail\Attachment $file
* @param array $options
* @return $this
*/
public function attach($file, array $options = [])
{
if ($file instanceof Attachable) {
$file = $file->toMailAttachment();
}
if ($file instanceof Attachment) {
return $file->attachTo($this, $options);
}
$this->attachments = collect($this->attachments)
->push(compact('file', 'options'))
->unique('file')
->all();
return $this;
}
/**
* Attach multiple files to the message.
*
* @param array $files
* @return $this
*/
public function attachMany($files)
{
foreach ($files as $file => $options) {
if (is_int($file)) {
$this->attach($options);
} else {
$this->attach($file, $options);
}
}
return $this;
}
/**
* Determine if the mailable has the given attachment.
*
* @param string|\Illuminate\Contracts\Mail\Attachable|\Illuminate\Mail\Attachment $file
* @param array $options
* @return bool
*/
public function hasAttachment($file, array $options = [])
{
if ($file instanceof Attachable) {
$file = $file->toMailAttachment();
}
if ($file instanceof Attachment && $this->hasEnvelopeAttachment($file, $options)) {
return true;
}
if ($file instanceof Attachment) {
$parts = $file->attachWith(
fn ($path) => [$path, [
'as' => $options['as'] ?? $file->as,
'mime' => $options['mime'] ?? $file->mime,
]],
fn ($data) => $this->hasAttachedData($data(), $options['as'] ?? $file->as, ['mime' => $options['mime'] ?? $file->mime])
);
if ($parts === true) {
return true;
}
[$file, $options] = $parts === false
? [null, []]
: $parts;
}
return collect($this->attachments)->contains(
fn ($attachment) => $attachment['file'] === $file && array_filter($attachment['options']) === array_filter($options)
);
}
/**
* Determine if the mailable has the given envelope attachment.
*
* @param \Illuminate\Mail\Attachment $attachment
* @param array $options
* @return bool
*/
private function hasEnvelopeAttachment($attachment, $options = [])
{
if (! method_exists($this, 'envelope')) {
return false;
}
$attachments = $this->attachments();
return Collection::make(is_object($attachments) ? [$attachments] : $attachments)
->map(fn ($attached) => $attached instanceof Attachable ? $attached->toMailAttachment() : $attached)
->contains(fn ($attached) => $attached->isEquivalent($attachment, $options));
}
/**
* Attach a file to the message from storage.
*
* @param string $path
* @param string|null $name
* @param array $options
* @return $this
*/
public function attachFromStorage($path, $name = null, array $options = [])
{
return $this->attachFromStorageDisk(null, $path, $name, $options);
}
/**
* Attach a file to the message from storage.
*
* @param string $disk
* @param string $path
* @param string|null $name
* @param array $options
* @return $this
*/
public function attachFromStorageDisk($disk, $path, $name = null, array $options = [])
{
$this->diskAttachments = collect($this->diskAttachments)->push([
'disk' => $disk,
'path' => $path,
'name' => $name ?? basename($path),
'options' => $options,
])->unique(function ($file) {
return $file['name'].$file['disk'].$file['path'];
})->all();
return $this;
}
/**
* Determine if the mailable has the given attachment from storage.
*
* @param string $path
* @param string|null $name
* @param array $options
* @return bool
*/
public function hasAttachmentFromStorage($path, $name = null, array $options = [])
{
return $this->hasAttachmentFromStorageDisk(null, $path, $name, $options);
}
/**
* Determine if the mailable has the given attachment from a specific storage disk.
*
* @param string $disk
* @param string $path
* @param string|null $name
* @param array $options
* @return bool
*/
public function hasAttachmentFromStorageDisk($disk, $path, $name = null, array $options = [])
{
return collect($this->diskAttachments)->contains(
fn ($attachment) => $attachment['disk'] === $disk
&& $attachment['path'] === $path
&& $attachment['name'] === ($name ?? basename($path))
&& $attachment['options'] === $options
);
}
/**
* Attach in-memory data as an attachment.
*
* @param string $data
* @param string $name
* @param array $options
* @return $this
*/
public function attachData($data, $name, array $options = [])
{
$this->rawAttachments = collect($this->rawAttachments)
->push(compact('data', 'name', 'options'))
->unique(function ($file) {
return $file['name'].$file['data'];
})->all();
return $this;
}
/**
* Determine if the mailable has the given data as an attachment.
*
* @param string $data
* @param string $name
* @param array $options
* @return bool
*/
public function hasAttachedData($data, $name, array $options = [])
{
return collect($this->rawAttachments)->contains(
fn ($attachment) => $attachment['data'] === $data
&& $attachment['name'] === $name
&& array_filter($attachment['options']) === array_filter($options)
);
}
/**
* Add a tag header to the message when supported by the underlying transport.
*
* @param string $value
* @return $this
*/
public function tag($value)
{
array_push($this->tags, $value);
return $this;
}
/**
* Determine if the mailable has the given tag.
*
* @param string $value
* @return bool
*/
public function hasTag($value)
{
return in_array($value, $this->tags) ||
(method_exists($this, 'envelope') && in_array($value, $this->envelope()->tags));
}
/**
* Add a metadata header to the message when supported by the underlying transport.
*
* @param string $key
* @param string $value
* @return $this
*/
public function metadata($key, $value)
{
$this->metadata[$key] = $value;
return $this;
}
/**
* Determine if the mailable has the given metadata.
*
* @param string $key
* @param string $value
* @return bool
*/
public function hasMetadata($key, $value)
{
return (isset($this->metadata[$key]) && $this->metadata[$key] === $value) ||
(method_exists($this, 'envelope') && $this->envelope()->hasMetadata($key, $value));
}
/**
* Assert that the mailable is from the given address.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertFrom($address, $name = null)
{
$this->renderForAssertions();
$recipient = $this->formatAssertionRecipient($address, $name);
PHPUnit::assertTrue(
$this->hasFrom($address, $name),
"Email was not from expected address [{$recipient}]."
);
return $this;
}
/**
* Assert that the mailable has the given recipient.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertTo($address, $name = null)
{
$this->renderForAssertions();
$recipient = $this->formatAssertionRecipient($address, $name);
PHPUnit::assertTrue(
$this->hasTo($address, $name),
"Did not see expected recipient [{$recipient}] in email recipients."
);
return $this;
}
/**
* Assert that the mailable has the given recipient.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertHasTo($address, $name = null)
{
return $this->assertTo($address, $name);
}
/**
* Assert that the mailable has the given recipient.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertHasCc($address, $name = null)
{
$this->renderForAssertions();
$recipient = $this->formatAssertionRecipient($address, $name);
PHPUnit::assertTrue(
$this->hasCc($address, $name),
"Did not see expected recipient [{$recipient}] in email recipients."
);
return $this;
}
/**
* Assert that the mailable has the given recipient.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertHasBcc($address, $name = null)
{
$this->renderForAssertions();
$recipient = $this->formatAssertionRecipient($address, $name);
PHPUnit::assertTrue(
$this->hasBcc($address, $name),
"Did not see expected recipient [{$recipient}] in email recipients."
);
return $this;
}
/**
* Assert that the mailable has the given "reply to" address.
*
* @param object|array|string $address
* @param string|null $name
* @return $this
*/
public function assertHasReplyTo($address, $name = null)
{
$this->renderForAssertions();
$replyTo = $this->formatAssertionRecipient($address, $name);
PHPUnit::assertTrue(
$this->hasReplyTo($address, $name),
"Did not see expected address [{$replyTo}] as email 'reply to' recipient."
);
return $this;
}
/**
* Format the mailable recipient for display in an assertion message.
*
* @param object|array|string $address
* @param string|null $name
* @return string
*/
private function formatAssertionRecipient($address, $name = null)
{
if (! is_string($address)) {
$address = json_encode($address);
}
if (filled($name)) {
$address .= ' ('.$name.')';
}
return $address;
}
/**
* Assert that the mailable has the given subject.
*
* @param string $subject
* @return $this
*/
public function assertHasSubject($subject)
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasSubject($subject),
"Did not see expected text [{$subject}] in email subject."
);
return $this;
}
/**
* Assert that the given text is present in the HTML email body.
*
* @param string $string
* @param bool $escape
* @return $this
*/
public function assertSeeInHtml($string, $escape = true)
{
$string = $escape ? e($string) : $string;
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertStringContainsString(
$string,
$html,
"Did not see expected text [{$string}] within email body."
);
return $this;
}
/**
* Assert that the given text is not present in the HTML email body.
*
* @param string $string
* @param bool $escape
* @return $this
*/
public function assertDontSeeInHtml($string, $escape = true)
{
$string = $escape ? e($string) : $string;
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertStringNotContainsString(
$string,
$html,
"Saw unexpected text [{$string}] within email body."
);
return $this;
}
/**
* Assert that the given text strings are present in order in the HTML email body.
*
* @param array $strings
* @param bool $escape
* @return $this
*/
public function assertSeeInOrderInHtml($strings, $escape = true)
{
$strings = $escape ? array_map('e', $strings) : $strings;
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertThat($strings, new SeeInOrder($html));
return $this;
}
/**
* Assert that the given text is present in the plain-text email body.
*
* @param string $string
* @return $this
*/
public function assertSeeInText($string)
{
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertStringContainsString(
$string,
$text,
"Did not see expected text [{$string}] within text email body."
);
return $this;
}
/**
* Assert that the given text is not present in the plain-text email body.
*
* @param string $string
* @return $this
*/
public function assertDontSeeInText($string)
{
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertStringNotContainsString(
$string,
$text,
"Saw unexpected text [{$string}] within text email body."
);
return $this;
}
/**
* Assert that the given text strings are present in order in the plain-text email body.
*
* @param array $strings
* @return $this
*/
public function assertSeeInOrderInText($strings)
{
[$html, $text] = $this->renderForAssertions();
PHPUnit::assertThat($strings, new SeeInOrder($text));
return $this;
}
/**
* Assert the mailable has the given attachment.
*
* @param string|\Illuminate\Contracts\Mail\Attachable|\Illuminate\Mail\Attachment $file
* @param array $options
* @return $this
*/
public function assertHasAttachment($file, array $options = [])
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasAttachment($file, $options),
'Did not find the expected attachment.'
);
return $this;
}
/**
* Assert the mailable has the given data as an attachment.
*
* @param string $data
* @param string $name
* @param array $options
* @return $this
*/
public function assertHasAttachedData($data, $name, array $options = [])
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasAttachedData($data, $name, $options),
'Did not find the expected attachment.'
);
return $this;
}
/**
* Assert the mailable has the given attachment from storage.
*
* @param string $path
* @param string|null $name
* @param array $options
* @return $this
*/
public function assertHasAttachmentFromStorage($path, $name = null, array $options = [])
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasAttachmentFromStorage($path, $name, $options),
'Did not find the expected attachment.'
);
return $this;
}
/**
* Assert the mailable has the given attachment from a specific storage disk.
*
* @param string $disk
* @param string $path
* @param string|null $name
* @param array $options
* @return $this
*/
public function assertHasAttachmentFromStorageDisk($disk, $path, $name = null, array $options = [])
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasAttachmentFromStorageDisk($disk, $path, $name, $options),
'Did not find the expected attachment.'
);
return $this;
}
/**
* Assert that the mailable has the given tag.
*
* @param string $tag
* @return $this
*/
public function assertHasTag($tag)
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasTag($tag),
"Did not see expected tag [{$tag}] in email tags."
);
return $this;
}
/**
* Assert that the mailable has the given metadata.
*
* @param string $key
* @param string $value
* @return $this
*/
public function assertHasMetadata($key, $value)
{
$this->renderForAssertions();
PHPUnit::assertTrue(
$this->hasMetadata($key, $value),
"Did not see expected key [{$key}] and value [{$value}] in email metadata."
);
return $this;
}
/**
* Render the HTML and plain-text version of the mailable into views for assertions.
*
* @return array
*
* @throws \ReflectionException
*/
protected function renderForAssertions()
{
if ($this->assertionableRenderStrings) {
return $this->assertionableRenderStrings;
}
return $this->assertionableRenderStrings = $this->withLocale($this->locale, function () {
$this->prepareMailableForDelivery();
$html = Container::getInstance()->make('mailer')->render(
$view = $this->buildView(), $this->buildViewData()
);
if (is_array($view) && isset($view[1])) {
$text = $view[1];
}
$text ??= $view['text'] ?? '';
if (! empty($text) && ! $text instanceof Htmlable) {
$text = Container::getInstance()->make('mailer')->render(
$text, $this->buildViewData()
);
}
return [(string) $html, (string) $text];
});
}
/**
* Prepare the mailable instance for delivery.
*
* @return void
*/
protected function prepareMailableForDelivery()
{
if (method_exists($this, 'build')) {
Container::getInstance()->call([$this, 'build']);
}
$this->ensureHeadersAreHydrated();
$this->ensureEnvelopeIsHydrated();
$this->ensureContentIsHydrated();
$this->ensureAttachmentsAreHydrated();
}
/**
* Ensure the mailable's headers are hydrated from the "headers" method.
*
* @return void
*/
private function ensureHeadersAreHydrated()
{
if (! method_exists($this, 'headers')) {
return;
}
$headers = $this->headers();
$this->withSymfonyMessage(function ($message) use ($headers) {
if ($headers->messageId) {
$message->getHeaders()->addIdHeader('Message-Id', $headers->messageId);
}
if (count($headers->references) > 0) {
$message->getHeaders()->addTextHeader('References', $headers->referencesString());
}
foreach ($headers->text as $key => $value) {
$message->getHeaders()->addTextHeader($key, $value);
}
});
}
/**
* Ensure the mailable's "envelope" data is hydrated from the "envelope" method.
*
* @return void
*/
private function ensureEnvelopeIsHydrated()
{
if (! method_exists($this, 'envelope')) {
return;
}
$envelope = $this->envelope();
if (isset($envelope->from)) {
$this->from($envelope->from->address, $envelope->from->name);
}
foreach (['to', 'cc', 'bcc', 'replyTo'] as $type) {
foreach ($envelope->{$type} as $address) {
$this->{$type}($address->address, $address->name);
}
}
if ($envelope->subject) {
$this->subject($envelope->subject);
}
foreach ($envelope->tags as $tag) {
$this->tag($tag);
}
foreach ($envelope->metadata as $key => $value) {
$this->metadata($key, $value);
}
foreach ($envelope->using as $callback) {
$this->withSymfonyMessage($callback);
}
}
/**
* Ensure the mailable's content is hydrated from the "content" method.
*
* @return void
*/
private function ensureContentIsHydrated()
{
if (! method_exists($this, 'content')) {
return;
}
$content = $this->content();
if ($content->view) {
$this->view($content->view);
}
if ($content->html) {
$this->view($content->html);
}
if ($content->text) {
$this->text($content->text);
}
if ($content->markdown) {
$this->markdown($content->markdown);
}
if ($content->htmlString) {
$this->html($content->htmlString);
}
foreach ($content->with as $key => $value) {
$this->with($key, $value);
}
}
/**
* Ensure the mailable's attachments are hydrated from the "attachments" method.
*
* @return void
*/
private function ensureAttachmentsAreHydrated()
{
if (! method_exists($this, 'attachments')) {
return;
}
$attachments = $this->attachments();
Collection::make(is_object($attachments) ? [$attachments] : $attachments)
->each(function ($attachment) {
$this->attach($attachment);
});
}
/**
* Set the name of the mailer that should send the message.
*
* @param string $mailer
* @return $this
*/
public function mailer($mailer)
{
$this->mailer = $mailer;
return $this;
}
/**
* Register a callback to be called with the Symfony message instance.
*
* @param callable $callback
* @return $this
*/
public function withSymfonyMessage($callback)
{
$this->callbacks[] = $callback;
return $this;
}
/**
* Register a callback to be called while building the view data.
*
* @param callable $callback
* @return void
*/
public static function buildViewDataUsing(callable $callback)
{
static::$viewDataCallback = $callback;
}
/**
* Dynamically bind parameters to the message.
*
* @param string $method
* @param array $parameters
* @return $this
*
* @throws \BadMethodCallException
*/
public function __call($method, $parameters)
{
if (static::hasMacro($method)) {
return $this->macroCall($method, $parameters);
}
if (str_starts_with($method, 'with')) {
return $this->with(Str::camel(substr($method, 4)), $parameters[0]);
}
static::throwBadMethodCallException($method);
}
}