The Mime Component

The Mime Component

The Mime component allows manipulating the MIME messages used to send emailsand provides utilities related to MIME types.

New in version 4.3: The Mime component was introduced in Symfony 4.3 and it's stillconsidered an experimental feature.

Installation

$ composer require symfony/mime

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Introduction

MIME (Multipurpose Internet Mail Extensions) is an Internet standard thatextends the original basic format of emails to support features like:

Headers and text contents using non-ASCII characters;
Message bodies with multiple parts (e.g. HTML and plain text contents);
Non-text attachments: audio, video, images, PDF, etc.The entire MIME standard is complex and huge, but Symfony abstracts all thatcomplexity to provide two ways of creating MIME messages:
A high-level API based on the Email classto quickly create email messages with all the common features;
A low-level API based on the Message classto have an absolute control over every single part of the email message.

Usage

Use the Email class and their _chainable_methods to compose the entire email message:

use Symfony\Component\Mime\Email;
 
$email = (new Email())
    ->from('[email protected]')
    ->to('[email protected]')
    ->cc('[email protected]')
    ->bcc('[email protected]')
    ->replyTo('[email protected]')
    ->priority(Email::PRIORITY_HIGH)
    ->subject('Important Notification')
    ->text('Lorem ipsum...')
    ->html('<h1>Lorem ipsum</h1> <p>...</p>')
;

This only purpose of this component is to create the email messages. Use theMailer component to actually send them. In Symfonyapplications, it's easier to use the Mailer integration.

Most of the details about how to create Email objects, including Twig integration,can be found in the Mailer documentation.

Twig Integration

The Mime component comes with excellent integration with Twig, allowing you tocreate messages from Twig templates, embed images, inline CSS and more. Detailson how to use those features can be found in the Mailer documentation:Twig: HTML & CSS.

But if you're using the Mime component without the Symfony framework, you'll needto handle a few setup details.

Twig Setup

To integrate with Twig, use the BodyRendererclass to render the template and update the email message contents with the results:

// ...
use Symfony\Bridge\Twig\Mime\BodyRenderer;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;
 
// when using the Mime component inside a full-stack Symfony application, you
// don't need to do this Twig setup. You only have to inject the 'twig' service
$loader = new FilesystemLoader(__DIR__.'/templates');
$twig = new Environment($loader);
 
$renderer = new BodyRenderer($twig);
// this updates the $email object contents with the result of rendering
// the template defined earlier with the given context
$renderer->render($email);

Inlining CSS Styles (and other Extensions)

To use the inline_css filter, first install the Twigextension:

$ composer require twig/cssinliner-extension

Now, enable the extension:

// ...
use Twig\CssInliner\CssInlinerExtension;
 
$loader = new FilesystemLoader(__DIR__.'/templates');
$twig = new Environment($loader);
$twig->addExtension(new CssInlinerExtension());

The same process should be used for enabling other extensions, like theMarkdownExtension and InkyExtension.

Creating Raw Email Messages

This is useful for advanced applications that need absolute control over everyemail part. It's not recommended for applications with regular emailrequirements because it adds complexity for no real gain.

Before continuing, it's important to have a look at the low level structure ofan email message. Consider a message which includes some content as both textand HTML, a single PNG image embedded in those contents and a PDF file attachedto it. The MIME standard allows structuring this message in different ways, butthe following tree is the one that works on most email clients:

multipart/mixed
├── multipart/related
│   ├── multipart/alternative
│   │   ├── text/plain
│   │   └── text/html
│   └── image/png
└── application/pdf

This is the purpose of each MIME message part:

multipart/alternative: used when two or more parts are alternatives of thesame (or very similar) content. The preferred format must be added last.
multipart/mixed: used to send different content types in the same message,such as when attaching files.
multipart/related: used to indicate that each message part is a componentof an aggregate whole. The most common usage is to display images embeddedin the message contents.When using the low-level Message class tocreate the email message, you must keep all the above in mind to define thedifferent parts of the email by hand:

use Symfony\Component\Mime\Header\Headers;
use Symfony\Component\Mime\Message;
use Symfony\Component\Mime\Part\Multipart\AlternativePart;
use Symfony\Component\Mime\Part\TextPart;
 
$headers = (new Headers())
    ->addMailboxListHeader('From', ['[email protected]'])
    ->addMailboxListHeader('To', ['[email protected]'])
    ->addTextHeader('Subject', 'Important Notification')
;
 
$textContent = new TextPart('Lorem ipsum...');
$htmlContent = new TextPart('<h1>Lorem ipsum</h1> <p>...</p>', 'html');
$body = new AlternativePart($textContent, $htmlContent);
 
$email = new Message($headers, $body);

Embedding images and attaching files is possible by creating the appropriateemail multiparts:

// ...
use Symfony\Component\Mime\Part\DataPart;
use Symfony\Component\Mime\Part\Multipart\MixedPart;
use Symfony\Component\Mime\Part\Multipart\RelatedPart;
 
// ...
$embeddedImage = new DataPart(fopen('/path/to/images/logo.png', 'r'), null, 'image/png');
$imageCid = $embeddedImage->getContentId();
 
$attachedFile = new DataPart(fopen('/path/to/documents/terms-of-use.pdf', 'r'), null, 'application/pdf');
 
$textContent = new TextPart('Lorem ipsum...');
$htmlContent = new TextPart(sprintf(
    '<img src="cid:%s"/> <h1>Lorem ipsum</h1> <p>...</p>', $imageCid
), 'html');
$bodyContent = new AlternativePart($textContent, $htmlContent);
$body = new RelatedPart($bodyContent, $embeddedImage);
 
$messageParts = new MixedPart($body, $attachedFile);
 
$email = new Message($headers, $messageParts);

Serializing Email Messages

Email messages created with either the Email or Message classes can beserialized because they are simple data objects:

$email = (new Email())
    ->from('[email protected]')
    // ...
;
 
$serializedEmail = serialize($email);

A common use case is to store serialized email messages, include them in amessage sent with the Messenger component andrecreate them later when sending them. Use theRawMessage class to recreate email messagesfrom their serialized contents:

use Symfony\Component\Mime\RawMessage;
 
// ...
$serializedEmail = serialize($email);
 
// later, recreate the original message to actually send it
$message = new RawMessage(unserialize($serializedEmail));

MIME Types Utilities

Although MIME was designed mainly for creating emails, the content types (alsoknown as MIME types and "media types") defined by MIME standards are also ofimportance in communication protocols outside of email, such as HTTP. That'swhy this component also provides utilities to work with MIME types.

The MimeTypes class transforms betweenMIME types and file name extensions:

use Symfony\Component\Mime\MimeTypes;
 
$mimeTypes = new MimeTypes();
$exts = $mimeTypes->getExtensions('application/javascript');
// $exts = ['js', 'jsm', 'mjs']
$exts = $mimeTypes->getExtensions('image/jpeg');
// $exts = ['jpeg', 'jpg', 'jpe']
 
$mimeTypes = $mimeTypes->getMimeTypes('js');
// $mimeTypes = ['application/javascript', 'application/x-javascript', 'text/javascript']
$mimeTypes = $mimeTypes->getMimeTypes('apk');
// $mimeTypes = ['application/vnd.android.package-archive']

These methods return arrays with one or more elements. The element positionindicates its priority, so the first returned extension is the preferred one.

Guessing the MIME Type

Another useful utility allows to guess the MIME type of any given file:

use Symfony\Component\Mime\MimeTypes;
 
$mimeTypes = new MimeTypes();
$mimeType = $mimeTypes->guessMimeType('/some/path/to/image.gif');
// Guessing is not based on the file name, so $mimeType will be 'image/gif'
// only if the given file is truly a GIF image

Guessing the MIME type is a time-consuming process that requires inspectingpart of the file contents. Symfony applies multiple guessing mechanisms, oneof them based on the PHP fileinfo extension. It's recommended to installthat extension to improve the guessing performance.

Adding a MIME Type Guesser

You can register your own MIME type guesser by creating a class that implementsMimeTypeGuesserInterface:

namespace App;
 
use Symfony\Component\Mime\MimeTypeGuesserInterface;
 
class SomeMimeTypeGuesser implements MimeTypeGuesserInterface
{
    public function isGuesserSupported(): bool
    {
        // return true when the guesser is supported (might depend on the OS for instance)
        return true;
    }
 
    public function guessMimeType(string $path): ?string
    {
        // inspect the contents of the file stored in $path to guess its
        // type and return a valid MIME type ... or null if unknown
 
        return '...';
    }
}