Manual:Adding support for new filetypes

Adding support for new file types to MediaWiki can be quite a daunting task. These are some of the steps you might have to take.

What do I need to do?

1. Check if no one has beat you to it. It might be that there is already an extension that handles uploads and thumbnailing for your file type. See Category:Media handling extensions
2. If already supported, make sure the file type is one of the filetypes allowed for uploading. See Manual:Configuring file uploads .
3. Do you only require support for uploading, or do you require support for embedding and thumbnailing?
4. Do you need the file format to be supported on Wikimedia websites? This introduces additional requirements with regard to performance, security and support of its communities.

Support for uploads

Further information: Manual:MIME type detection and Manual:Uploading

1. Add support for the MIME type to MediaWiki:
   1. includes/libs/mime/MimeMap.php
      • Add Mime to file-extension mapping in the MIME_EXTENSIONS array. (The preferred file extension goes first in the list)
      • Add Mime to media type matching, via one of the subarray MEDIATYPE_IMAGE, MEDIATYPE_AUDIO, MEDIATYPE_OFFICE etc.
   2. includes/libs/mime/MimeAnalyzer.php
      • If possible add the magic number to this file to make sure that we do not depend on external dependencies for detection.
   3. Add example files (as small as possible and copyright free) to tests/phpunit/data/media
   4. Add a testcase for filetype detection into tests/phpunit/includes/libs/mime/MimeAnalyzerTest.php
2. Add the file type to $wgFileExtensions to allow the upload on your server.

Note that MediaWiki has default checks for zip file formats, blocks java code and things that might be interpreted as HTML files. If your file format falls into this category, you either need to disable some of those protections (which is not advisable for publicly hosted servers) or implement additional logic.

Support thumbnailing and embedding

1. Determine if you need support in MediaWiki core. Usually exotic formats, formats with lots of dependencies or with special functionality will go in dedicated extensions. Examples of such extensions are: 3D, PagedTiffHandler and more.
2. Create a MediaHandler subclass for your filetype. For common cases like images, you can often extend from the subclass BitmapHandler instead. Here you can implement:
   1. Reading the metadata of the file
   2. Define what the behaviour should be (thumbnailing, embedding/render, paging etc).
   3. Implement if the code to do some of that behaviour, like thumbnailing and metadata reading.
   4. Note that the file format of your thumbnail is allowed to be different from your original file format.

   See other image handlers in: includes/media subdirectory of MediaWiki

3. Register your MediaHandler in includes/media/MediaHandlerFactory.php for core handlers, or in your extension.json if you have created an extension.

Support on Wikimedia websites

1. The format should be free from patents (Free and open).
2. The format should not allow execution of code when downloaded and executed on the computer of clients, like for instance macros or an embedded scripting language (if it does you will need to scan/sanitize the uploads from within MediaWiki)
3. If you are adding a new extension, an external library or console tool, then these will require a security review.
4. Your thumbnail format should be a commonly supported format for all browsers.
5. Your thumbnail (esp when interactive) should be usable when printing and for screenreader users
6. Interactive content should not reflow the page
7. Interactive content should perform (JS needs to be added only to the pages that require it etc).
8. Anything over $wgMaxImageArea in size requires special support, due to memory limitations. See also VipsScaler.
9. You need a thumbor engine to support making thumbnails of your images. All Wikimedia requests use a thumbor engine to do the actual thumbnail generation, instead of the thumbnail support inside the MediaHandler.
10. Check if the Wikimedia communities support adding this file format (Hold an RFC)