The Mime Component (Symfony Docs) (original) (raw)

Edit this page

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

Installation

Note

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

Introduction

MIME (Multipurpose Internet Mail Extensions) is an Internet standard that extends 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 that complexity to provide two ways of creating MIME messages:

• A high-level API based on the Email class to quickly create email messages with all the common features;
• A low-level API based on the Message class to have 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:

The only purpose of this component is to create the email messages. Use theMailer component to actually send them.

Twig Integration

The Mime component comes with excellent integration with Twig, allowing you to create messages from Twig templates, embed images, inline CSS and more. Details on 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 need to 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:

Creating Raw Email Messages

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

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

This is the purpose of each MIME message part:

• multipart/alternative: used when two or more parts are alternatives of the same (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 component of an aggregate whole. The most common usage is to display images embedded in the message contents.

When using the low-level Message class to create the email message, you must keep all the above in mind to define the different parts of the email by hand:

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

Serializing Email Messages

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

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

MIME Types Utilities

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

The MimeTypes class transforms between MIME types and file name extensions:

These methods return arrays with one or more elements. The element position indicates 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:

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

This work, including the code samples, is licensed under aCreative Commons BY-SA 3.0 license.