README

Comprehensive MIME type mapping API, PHP clone of broofa/node-mime. MIME database from jshttp/mime-db.

Data sources

This library uses the mime-db repository. The updates are automatically pulled from their repository, using bin/pull-mime-db.php [out] [--with-apache].

By default this library exposes merged nginx + mime-db "custom types" (119 usable mimes) and extensions. Those are the most commons types of the Internet. The library also includes the Apache types. A lot of Apache types are, in most part, useless and they are very numerous (884 usable mimes), so, in order to reduce the memory footprint, Apache types are not loaded by default.

If you're searching for a library with more options and features, check hoaproject/Mime. If you need something simple, this library is for you ! For example, this library is perfect to implement a HTTP server that serves static files with a mime type based on the extension - since MIME scanning is too slow.

Install & Usage

composer require alembic/mime

use Alembic\Mime\Mime;

Note: All the methods exposed below can be called statically or with an instance of the Mime class (more practical in DI environments). Please note that, even when using instance calls, the MIMEs database is shared because it is static.

API — Queries

Mime::lookup($path [, $fallback])

Get the mime type associated with a file, if no mime type is found $fallback (Mime::$defaultType by default, which is application/octet-stream) is returned. Performs a case-insensitive lookup using the extension in $path (the substring after the last '.'). E.g.

use Alembic\Mime\Mime;

Mime::lookup('/path/to/file.txt');         # => 'text/plain'
Mime::lookup('file.txt');                  # => 'text/plain'
Mime::lookup('.TXT');                      # => 'text/plain'
Mime::lookup('htm');                       # => 'text/html'
Mime::lookup('unknown');                   # => 'application/octet-stream'
Mime::lookup('unknown', null);             # => null
# Instance mode:
(new Mime)->lookup('folder/file');         # => 'application/octet-stream'

Mime::$defaultType

The mime type returned when Mime::lookup fails to find the extension searched for (default is the standard application/octet-stream).

Mime::extension($type)

Get the preferred extension for $type.

Mime::extension('text/html');                 # => 'html'
Mime::extension('application/octet-stream');  # => 'bin'

Mime::$defaultExtension

The extension returned when Mime::extension fails to find the type searched for (warning, default is null).

API — Defining Types

Custom type mappings can be added on a per-project basis via the following APIs.

Mime::define()

Add custom mime/extension mappings.

Mime::define([
    'text/x-some-format'      => ['x-sf', 'x-sft', 'x-sfml'],
    'application/x-my-type'   => ['x-mt', 'x-mtt'],
    'application/x-my-format' => 'x-mf', # string allowed for unique ext
    # etc ...
]);

Mime::lookup('x-sft');  # => 'text/x-some-format'

As said before, the first entry in the extensions array is returned by Mime::extension(). E.g.

Mime::extension('text/x-some-format');  # => 'x-sf'

Mime::load($filepath)

Load mappings from an Apache ".types" file or a Nginx file containing a types block. The format (Nginx or Apache) is automagically detected based on the content. Since the library uses file_get_contents(), the $filepath argument could be a filesystem path, an FTP path, an URL, whatever. If the file couldn't be loaded (wrong path or insufficient privileges), it throws a \RuntimeException.

Mime::load('./my_project.types');

The Apache .types file or the Nginx types block format is simple — see the examples directory for examples.

Mime::apacheExtend()

Loads the packaged database of merged mime-db+nginx+Apache MIME types and extensions. The basic database (mime-db+nginx) is loaded by default and weighs 8 KiB, when the all-in-one database loaded by this method weighs 70 KiB.

alembic / mime

Maintainers

Details