Added the MIME Types Utilities section

symfony · javiereguiluz · Apr 2, 2019 · Apr 3, 2019 · Apr 3, 2019 · Apr 3, 2019
commit ec9f85832a35baeecb2181e5b3b48d98cdf9c679
diff --git a/components/mime.rst b/components/mime.rst
@@ -6,7 +6,8 @@
 The Mime Component
 ==================
 
-    The MIME component allows manipulating the MIME messages used to send emails.
+    The MIME component allows manipulating the MIME messages used to send emails
+    and provides utilities related to MIME types.
 
 Installation
 ------------
@@ -282,15 +283,11 @@ from their serialized contents::
 
     use Symfony\Component\Mime\RawMessage;
 
-    // create the email and serialize it for later reuse
-    $email = (new Email())
-        ->from('fabien@symfony.com')
-        // ...
-    ;
+    // ...
     $serializedEmail = serialize($email);
 
     // later, recreate the original message to actually send it
-    $message = new RawMessage($serializedEmail);
+    $message = new RawMessage(unserialize($serializedEmail));
 
 .. _mime-component-twig-integration:
 
@@ -571,7 +568,80 @@ You can combine all filters to create complex email messages:
         {# ... #}
     {% endfilter %}
 
+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 :class:`Symfony\\Component\\Mime\\MimeTypes` class transforms between
+MIME 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 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::
+
+    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 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.
+
+Adding a MIME Type Guesser
+..........................
+
+You can register your own MIME type guesser by creating a class that implements
+:class:`Symfony\\Component\\Mime\\MimeTypeGuesserInterface`::
+
+    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 '...';
+        }
+    }
+
 .. _`MIME`: https://en.wikipedia.org/wiki/MIME
 .. _`league/html-to-markdown`: https://github.com/thephpleague/html-to-markdown
 .. _`Markdown syntax`: https://commonmark.org/
 .. _`Inky`: https://foundation.zurb.com/emails.html
+.. _`MIME types`: https://en.wikipedia.org/wiki/Media_type
+.. _`fileinfo extension`: https://php.net/fileinfo