From bd2531246bc92869320e2ae26ddc7a8475fa5828 Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Tue, 15 Jan 2019 17:52:27 +0100 Subject: [PATCH 1/2] added docs for the Mime component --- components/mime.rst | 67 ++++++++++++++++++++++++++++++++++++++++++ reference/dic_tags.rst | 10 +++++++ 2 files changed, 77 insertions(+) create mode 100644 components/mime.rst diff --git a/components/mime.rst b/components/mime.rst new file mode 100644 index 00000000000..901606f91f9 --- /dev/null +++ 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 ``_ 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 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 From 5f5654073e2ad877090c22c99398cf551bcdb53e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 17 Jan 2019 13:17:31 +0100 Subject: [PATCH 2/2] Proposed some rewords Instead of adding comments about possible changes, I've decided to commit them. Revert totally or partially if you disagree with them. Thanks! --- components/mime.rst | 55 +++++++++++++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 17 deletions(-) diff --git a/components/mime.rst b/components/mime.rst index 901606f91f9..84ca31cdbce 100644 --- a/components/mime.rst +++ b/components/mime.rst @@ -5,7 +5,8 @@ The MIME Component ================== - The MIME component allows manipulating MIME types. + The MIME component provides utilities related to MIME types, such as + guessing the MIME type of a given file. Installation ------------ @@ -18,27 +19,44 @@ Alternatively, you can clone the ``_ repository .. include:: /components/require_autoload.rst.inc -.. tip:: +MIME Types Utilities +-------------------- - 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:: +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/mbox'); - // $exts contains an array of extensions: ['mbox'] + $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'] - $mimeTypes = $mimeTypes->getMimeTypes('mbox'); - // $mimeTypes contains an array of MIME types: ['application/mbox'] +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). - // guess a mime type for a file +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,8 +78,11 @@ You can register your own MIME type guesser by creating a class that extends 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'; + // 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