added docs for the Mime component

symfony · fabpot · Jan 15, 2019 · Jan 17, 2019 · Jan 16, 2019 · bd2531246bc92869320e2ae26ddc7a8475fa5828
commit bd2531246bc92869320e2ae26ddc7a8475fa5828
diff --git a/components/mime.rst b/components/mime.rst
@@ -0,0 +1,67 @@
+.. index::
+    single: MIME
+    single: Components; MIME
+
+The MIME Component
+==================
+
+    The MIME component allows manipulating MIME types.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/mime
+
+Alternatively, you can clone the `<https://github.com/symfony/mime>`_ repository.
+
+.. include:: /components/require_autoload.rst.inc
+
+.. tip::
+
+    You should have the ``fileinfo`` PHP extension installed for greater performance.
+
+MIME Types
+----------
+
+The :class:`Symfony\\Component\\Mime\\MimeTypes` class manipulates the
+relationships between MIME types and file name extensions::
+
+    use Symfony\Component\Mime\MimeTypes;
+
+    $mimeTypes = new MimeTypes();
+    $exts = $mimeTypes->getExtensions('application/mbox');
+    // $exts contains an array of extensions: ['mbox']
+
+    $mimeTypes = $mimeTypes->getMimeTypes('mbox');
+    // $mimeTypes contains an array of MIME types: ['application/mbox']
+
+    // guess a mime type for a file
+    $mimeType = $mimeTypes->guessMimeType('/some/path/to/image.gif');
+
+Adding a MIME Type Guesser
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can register your own MIME type guesser by creating a class that extends
+: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
+        {
+            // return a MIME type based on the content of the file stored in $path
+            // you MUST not use the filename to determine the MIME type.
+            return 'text/plain';
+        }
+    }
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -25,6 +25,7 @@ Tag Name                                  Usage
 `kernel.event_listener`_                  Listen to different events/hooks in Symfony
 `kernel.event_subscriber`_                To subscribe to a set of different events/hooks in Symfony
 `kernel.fragment_renderer`_               Add new HTTP content rendering strategies
+`mime.mime_type_guesser`_                 Add a custom mime type guesser to MimeTypes
 `monolog.logger`_                         Logging with a custom logging channel
 `monolog.processor`_                      Add a custom processor for logging
 `routing.loader`_                         Register a custom service that loads routes
@@ -450,6 +451,15 @@ To add a new rendering strategy - in addition to the core strategies like
 :class:`Symfony\\Component\\HttpKernel\\Fragment\\FragmentRendererInterface`,
 register it as a service, then tag it with ``kernel.fragment_renderer``.
 
+mime.mime_type_guesser
+----------------------
+
+**Purpose**: Add a custom MIME type guesser to MimeTypes
+
+To add a custom MIME type guesser - in addition to the core guessers - create a
+class that implements :class:`Symfony\\Component\\Mime\\MimeTypes`, register it
+as a service, then tag it with ``mime.mime_type_guesser``.
+
 .. _dic_tags-monolog:
 
 monolog.logger