You are here

Home » API reference » MimeDetect 8

README.txt in MimeDetect 8

Same filename and directory in other branches
  1. 5 README.txt
  2. 6 README.txt
  3. 7 README.txt
MIMEDETECT DRUPAL MODULE
========================

CONTENTS OF THIS FILE
---------------------

 * Summary
 * Requirements
 * Installation
 * Configuration
 * Usage
 * Recommended modules
 * Troubleshooting
 * Contact
 * Credits


SUMMARY
-------

MimeDetect provides a MIME detection API. Detection itself is done following
these steps:

 1. MIME detection plugins
    If a detection plugin for the given filename extension exists, it is
    executed. When MIME detection by plugins succeeds, the detected MIME type
    is returned and no more methods will be tested.

 2. Fileinfo PHP extension
    Used if enabled (in config) and such PHP extension is available in your
    system. Detection will stop here when a result different from the generic
    "application/octet-stream" is obtained.

 3. UNIX file command
    Disabled by default, it is used when present.

 4. Core MIME type guesser is used as a fallback.
    This is the default MIME type dectection in Drupal and is based only on
    a mapping between filename extensions and the corresponding MIME types.

MimeDetect also includes a submodule for file upload protection against
inconsistent filename extension with its real content.


REQUIREMENTS
------------

At least one of these two supported tools based on MIME 'magic' detection has to
be present in your system:

 1. PHP File information extension
    Commonly included in the basic PHP installation.
    see: http://php.net/manual/en/book.fileinfo.php

 2. UNIX 'file' command
    Present on most UNIX/Linux systems.
    see: https://en.wikipedia.org/wiki/File_(command)


INSTALLATION
------------

Install as usual, see https://www.drupal.org/node/1897420 for further
information.


CONFIGURATION
-------------

Module configuration is available at Manage -> Configuration -> Media
(/admin/config/media/mimedetect).

By default, only the PHP fileinfo detection engine is enabled.


USAGE
-----

MimeDetect acts as an API, other modules can make usage of it by using the
'mimedetect' service.

A simple file upload validator is included in a separate module for illustration
purposes, basic functionality and backward compatibility with Drupal 6 & 7. It
rejects any file upload which detected MIME type doesn't match the filename
extension.


RECOMMENDED MODULES
-------------------

 * File MIME (https://www.drupal.org/project/filemime):
   Provides a way to alter the core MIME type mapping to file name extensions.
   Use it to add unrecognized extensions or to alter the MIME associated with
   some particular extension.


MIME DETECTION PLUGINS
----------------------

Not all file content types can be determined by MIME 'magic' method. In such
cases a programmatic method has to be implemented as a plugin. For example, CSV
files are detected as "text/plain" by the PHP fileinfo or the file UNIX
command. MimeDetect comes with a plugin to detect CSV files by examining their
real content.


TROUBLESHOOTING
---------------

File upload validation with unrecognized file name extensions:

Drupal core maps each file extension with a MIME type. Thats the way the
"file.mime_type.guesser" service guesses the MIME type for a given file name.

Some file name extensions are not present on such map or can be mapped with a
different MIME type than the detected by MimeDetect. For example, that's the
case for portable object (".po") files. PO files are plain text files that
contain translation strings. Drupal core returns the generic
'application/octet-stream' MIME type for them, whereas 'magic' MIME detection
engines (and therefore MimeDetect) usually returns 'text/x-po' as the detected
MIME type.

This mismatch will make file upload validator to block file uploading. The
right way to solve this is by altering the Drupal core file name extension map,
adding the unrecognized MIME types or overriding existing ones. And that's
exactly what the filemime recommended module does, so you will find this module
useful to solve these scenarios.


CONTACT
-------

Current maintainers:
* Manuel Adan (manuel.adan) - https://www.drupal.org/user/516420


CREDITS
-------

Ported to D8 by:
* Manuel Adan (manuel.adan) - https://www.drupal.org/user/516420

Ported to D6 & D7 by:
* andrew morton (drewish) - https://www.drupal.org/user/34869

Created by:
* Darrel O'Pry (dopry) - https://www.drupal.org/user/22202

File

README.txt
View source 
  1. MIMEDETECT DRUPAL MODULE

  2. ========================

  3. 

  4. CONTENTS OF THIS FILE

  5. ---------------------

  6. 

  7.  * Summary

  8.  * Requirements

  9.  * Installation

  10.  * Configuration

  11.  * Usage

  12.  * Recommended modules

  13.  * Troubleshooting

  14.  * Contact

  15.  * Credits

  16. 

  17. 

  18. SUMMARY

  19. -------

  20. 

  21. MimeDetect provides a MIME detection API. Detection itself is done following

  22. these steps:

  23. 

  24.  1. MIME detection plugins

  25.     If a detection plugin for the given filename extension exists, it is

  26.     executed. When MIME detection by plugins succeeds, the detected MIME type

  27.     is returned and no more methods will be tested.

  28. 

  29.  2. Fileinfo PHP extension

  30.     Used if enabled (in config) and such PHP extension is available in your

  31.     system. Detection will stop here when a result different from the generic

  32.     "application/octet-stream" is obtained.

  33. 

  34.  3. UNIX file command

  35.     Disabled by default, it is used when present.

  36. 

  37.  4. Core MIME type guesser is used as a fallback.

  38.     This is the default MIME type dectection in Drupal and is based only on

  39.     a mapping between filename extensions and the corresponding MIME types.

  40. 

  41. MimeDetect also includes a submodule for file upload protection against

  42. inconsistent filename extension with its real content.

  43. 

  44. 

  45. REQUIREMENTS

  46. ------------

  47. 

  48. At least one of these two supported tools based on MIME 'magic' detection has to

  49. be present in your system:

  50. 

  51.  1. PHP File information extension

  52.     Commonly included in the basic PHP installation.

  53.     see: http://php.net/manual/en/book.fileinfo.php

  54. 

  55.  2. UNIX 'file' command

  56.     Present on most UNIX/Linux systems.

  57.     see: https://en.wikipedia.org/wiki/File_(command)

  58. 

  59. 

  60. INSTALLATION

  61. ------------

  62. 

  63. Install as usual, see https://www.drupal.org/node/1897420 for further

  64. information.

  65. 

  66. 

  67. CONFIGURATION

  68. -------------

  69. 

  70. Module configuration is available at Manage -> Configuration -> Media

  71. (/admin/config/media/mimedetect).

  72. 

  73. By default, only the PHP fileinfo detection engine is enabled.

  74. 

  75. 

  76. USAGE

  77. -----

  78. 

  79. MimeDetect acts as an API, other modules can make usage of it by using the

  80. 'mimedetect' service.

  81. 

  82. A simple file upload validator is included in a separate module for illustration

  83. purposes, basic functionality and backward compatibility with Drupal 6 & 7. It

  84. rejects any file upload which detected MIME type doesn't match the filename

  85. extension.

  86. 

  87. 

  88. RECOMMENDED MODULES

  89. -------------------

  90. 

  91.  * File MIME (https://www.drupal.org/project/filemime):

  92.    Provides a way to alter the core MIME type mapping to file name extensions.

  93.    Use it to add unrecognized extensions or to alter the MIME associated with

  94.    some particular extension.

  95. 

  96. 

  97. MIME DETECTION PLUGINS

  98. ----------------------

  99. 

  100. Not all file content types can be determined by MIME 'magic' method. In such

  101. cases a programmatic method has to be implemented as a plugin. For example, CSV

  102. files are detected as "text/plain" by the PHP fileinfo or the file UNIX

  103. command. MimeDetect comes with a plugin to detect CSV files by examining their

  104. real content.

  105. 

  106. 

  107. TROUBLESHOOTING

  108. ---------------

  109. 

  110. File upload validation with unrecognized file name extensions:

  111. 

  112. Drupal core maps each file extension with a MIME type. Thats the way the

  113. "file.mime_type.guesser" service guesses the MIME type for a given file name.

  114. 

  115. Some file name extensions are not present on such map or can be mapped with a

  116. different MIME type than the detected by MimeDetect. For example, that's the

  117. case for portable object (".po") files. PO files are plain text files that

  118. contain translation strings. Drupal core returns the generic

  119. 'application/octet-stream' MIME type for them, whereas 'magic' MIME detection

  120. engines (and therefore MimeDetect) usually returns 'text/x-po' as the detected

  121. MIME type.

  122. 

  123. This mismatch will make file upload validator to block file uploading. The

  124. right way to solve this is by altering the Drupal core file name extension map,

  125. adding the unrecognized MIME types or overriding existing ones. And that's

  126. exactly what the filemime recommended module does, so you will find this module

  127. useful to solve these scenarios.

  128. 

  129. 

  130. CONTACT

  131. -------

  132. 

  133. Current maintainers:

  134. * Manuel Adan (manuel.adan) - https://www.drupal.org/user/516420

  135. 

  136. 

  137. CREDITS

  138. -------

  139. 

  140. Ported to D8 by:

  141. * Manuel Adan (manuel.adan) - https://www.drupal.org/user/516420

  142. 

  143. Ported to D6 & D7 by:

  144. * andrew morton (drewish) - https://www.drupal.org/user/34869

  145. 

  146. Created by:

  147. * Darrel O'Pry (dopry) - https://www.drupal.org/user/22202