diff --git a/components/mime.rst b/components/mime.rst new file mode 100644 index 00000000000..84ca31cdbce --- /dev/null +++ b/components/mime.rst @@ -0,0 +1,88 @@ +.. index:: + single: MIME + single: Components; MIME + +The MIME Component +================== + + The MIME component provides utilities related to MIME types, such as + guessing the MIME type of a given file. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/mime + +Alternatively, you can clone the ``_ repository. + +.. include:: /components/require_autoload.rst.inc + +MIME Types Utilities +-------------------- + +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 (e.g. the first returned extension is the preferred one). + +Guessing the MIME Type +---------------------- + +This component also guesses 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 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 + { + // inspect the contents of the file stored in $path to guess its + // type and return a valid MIME type ... or null if unknown + + return '...'; + } + } + +.. _`fileinfo extension`: https://php.net/fileinfo diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index f46e1041d8d..e5bad79c148 100644 --- 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