README

A modern, extensible MIME type detector for PHP that analyses the initial bytes of a file instead of trusting its extension. The detector ships with a modular pipeline of signature matchers and a bidirectional repository of MIME type ↔ extension mappings. Signature detection is a best-effort format hint; validate file structure and apply upload policy separately when handling untrusted files.

Features

Real file inspection – identifies file formats by signature instead of relying on filenames. You can find a list of supported file formats in the Wiki.
Composable architecture – category-specific detectors can be swapped in or extended without touching the core.
Rich lookup helpers – translate between MIME types and extensions in both directions and enumerate the supported catalogue.
No runtime packages – requires PHP 8.1+ and ext-ctype. It uses ZipArchive for deeper ZIP inspection when that extension is available.

Installation

Install the package via Composer:

composer require softcreatr/php-mime-detector

Quick start

Detecting the MIME type and the preferred extension for a file is as simple as instantiating the façade and calling its helpers:

<?php

use SoftCreatR\MimeDetector\MimeDetector;
use SoftCreatR\MimeDetector\MimeDetectorException;

require 'vendor/autoload.php';

try {
    $detector = new MimeDetector(__DIR__ . '/example.png');

    echo $detector->getMimeType();       // image/png
    echo $detector->getFileExtension();  // png
    echo $detector->getFileHash();       // crc32 hash of the file contents
} catch (MimeDetectorException $exception) {
    // React to unreadable files.
    echo $exception->getMessage();
}

Resolving MIME types and extensions

The façade exposes several lookup helpers that do not require a file scan. They operate on the shared repository of known mappings:

$detector = new MimeDetector(__DIR__ . '/example.png');

// Retrieve a preferred extension for a MIME type.
$extension = $detector->getExtensionForMimeType('image/jpeg'); // "jpg"

// List every MIME type that corresponds to the given extension.
$mimeTypes = $detector->getMimeTypesForExtension('heic');

// Fetch the complete map as [mimeType => list of extensions].
$catalogue = $detector->listAllMimeTypes();

Comparing MIME names

Some tools use different names for the same format. Most existing MIME return values are preserved, but newly distinguished formats have new results; see the upgrade notes. Use MimeTypeAliases to compare a detector result with another source, such as PHP's fileinfo, or to request a preferred name:

use SoftCreatR\MimeDetector\MimeTypeAliases;

$detected = $detector->getMimeType(); // audio/vnd.wave for a WAV file
$fileinfo = 'audio/x-wav';

if (!MimeTypeAliases::equivalent($detected, $fileinfo)) {
    // Review the difference before applying the upload policy.
}

$preferred = $detector->getPreferredMimeType(); // audio/vnd.wave

The alias list is deliberately conservative. In particular, audio/ogg and audio/opus, or font/sfnt and font/ttf, describe different levels of a format and are not treated as interchangeable. Unknown names only match when their normalized names are identical. The preferred name is not guaranteed to be IANA registered for every format.

For Ogg Opus files, getMimeType() still returns the legacy audio/opus value, while getPreferredMimeType() returns the audio/ogg container type recommended by RFC 7845. The generic alias helper does not equate codec and container names.

Need a data URI? The detector will encode the configured file for you:

$dataUri = $detector->getBase64DataURI();
// data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Optional ZipArchive support

The detector is fully functional without PHP's ZipArchive extension; ZIP signatures are recognised by scanning the first 4 KiB of the file for well-known markers such as mimetype, [Content_Types].xml, or classes.dex. When the extension is present, the ZipSignatureDetector opens the archive and inspects its entries directly. This deeper look allows the detector to resolve format families like OOXML (.docx, .pptx, .xlsx), APK/JAR/XPI bundles, and iWork (.pages, .numbers, .key) even when their identifying data lives deeper inside the archive than the cached bytes. iWork classification reads a bounded portion of Index/Document.iwa; shared ZIP entry names alone cannot distinguish Pages from Numbers.

If the extension is missing, the detector simply falls back to its heuristic path and ultimately reports a generic application/zip match whenever a more specific signature cannot be derived. Unit tests that require ZipArchive are skipped automatically when the class is not available, so no additional setup is needed to run the suite.

ISO 9660 images are identified from their volume descriptor at sector 16. This requires a seekable file; an input that cannot be sought falls back to the other detectors.

Extending the detector

Custom formats can be added without modifying the library itself. Choose the approach that fits your needs best.

Registering detectors via extensions

When you only need to extend the default pipeline, extensions are the quickest way to plug in extra detectors. The snippet below is a complete, copy & paste ready bootstrap that you can drop into a service provider, bootstrap.php, or any other file that runs before you instantiate the façade:

<?php

declare(strict_types=1);

use App\MimeDetector\CustomContainerDetector;
use SoftCreatR\MimeDetector\MimeDetector;
use SoftCreatR\MimeDetector\MimeDetectorException;
use SoftCreatR\MimeDetector\MimeTypeDetector;
use SoftCreatR\MimeDetector\MimeTypeRepository;

require __DIR__ . '/vendor/autoload.php';

// 1) Teach the repository about your MIME type ↔ extension mapping.
$repository = MimeTypeRepository::createDefault();
$repository->register('custom', 'application/x-custom');

// 2) Register one or more detectors as an extension. Higher priorities run first.
MimeTypeDetector::extend(
    'custom-container',
    static function (): array {
        return [
            new CustomContainerDetector(),
            // More detectors can be returned from the same extension when needed.
        ];
    },
    priority: 150,
);

// 3) Resolve files like usual – the default pipeline now includes your extension.
try {
    $detector = new MimeDetector(__DIR__ . '/file.cust', $repository);

    echo $detector->getMimeType();      // application/x-custom
    echo $detector->getFileExtension(); // custom
} catch (MimeDetectorException $exception) {
    echo $exception->getMessage();
}

Extensions can be forgotten at runtime (MimeTypeDetector::forgetExtension('custom-container')) or reset entirely (MimeTypeDetector::flushExtensions()). Returning multiple detectors from an extension lets you register related matchers in one go while still benefiting from the priority-based ordering.

Building a custom pipeline

For more advanced scenarios you can compose a bespoke pipeline. Follow these steps to teach the detector about a new signature and MIME mapping.

1. Implement a signature detector

Create a class that implements SoftCreatR\MimeDetector\Contract\FileSignatureDetectorInterface. The detector receives the DetectionContext, which gives access to the file buffer and lets you return a MimeTypeMatch when the signature is recognised.

<?php

namespace App\MimeDetector;

use SoftCreatR\MimeDetector\Attribute\DetectorCategory;
use SoftCreatR\MimeDetector\Contract\FileSignatureDetectorInterface;
use SoftCreatR\MimeDetector\Detection\DetectionContext;
use SoftCreatR\MimeDetector\Detection\MimeTypeMatch;

#[DetectorCategory('custom')]
final class CustomContainerDetector implements FileSignatureDetectorInterface
{
    public function detect(DetectionContext $context): ?MimeTypeMatch
    {
        $buffer = $context->buffer();

        if ($buffer->checkForBytes([0x43, 0x55, 0x53, 0x54])) { // "CUST"
            return new MimeTypeMatch('custom', 'application/x-custom');
        }

        return null;
    }
}

2. Register MIME mappings

Extend the repository so your MIME type resolves to the expected extension(s):

use SoftCreatR\MimeDetector\MimeTypeRepository;

$repository = MimeTypeRepository::createDefault();
$repository->register('custom', 'application/x-custom');

3. Compose (or customise) the detector pipeline

Most projects do not need to rebuild the pipeline manually. Once an extension is registered it is automatically merged with the default signature detectors in priority order:

use SoftCreatR\MimeDetector\MimeDetector;
use SoftCreatR\MimeDetector\MimeTypeDetector;

MimeTypeDetector::extend(
    'custom-container',
    new CustomContainerDetector(),
    priority: 50, // run before the bundled detectors
);

$detector = new MimeDetector(__DIR__ . '/file.cust', $repository);

$match = $detector->getMimeType(); // application/x-custom

If you do need full control you can still provide a bespoke pipeline. Simply prepend your detector to the default ones so it executes before the fallback signatures:

use SoftCreatR\MimeDetector\Detection\DetectorPipeline;
use SoftCreatR\MimeDetector\Detector\ArchiveSignatureDetector;
use SoftCreatR\MimeDetector\Detector\DocumentSignatureDetector;
use SoftCreatR\MimeDetector\Detector\ExecutableSignatureDetector;
use SoftCreatR\MimeDetector\Detector\FontSignatureDetector;
use SoftCreatR\MimeDetector\Detector\ImageSignatureDetector;
use SoftCreatR\MimeDetector\Detector\MediaSignatureDetector;
use SoftCreatR\MimeDetector\Detector\MiscSignatureDetector;
use SoftCreatR\MimeDetector\Detector\XmlSignatureDetector;
use SoftCreatR\MimeDetector\Detector\ZipSignatureDetector;
use SoftCreatR\MimeDetector\MimeDetector;

$pipeline = DetectorPipeline::create(
    new CustomContainerDetector(),
    new ImageSignatureDetector(),
    new ZipSignatureDetector(),
    new ArchiveSignatureDetector(),
    new MediaSignatureDetector(),
    new DocumentSignatureDetector(),
    new FontSignatureDetector(),
    new ExecutableSignatureDetector(),
    new MiscSignatureDetector(),
    new XmlSignatureDetector(),
);

$detector = new MimeDetector(__DIR__ . '/file.cust', $repository, $pipeline);

From this point the new MIME type behaves exactly like the built-in ones – it can be detected from files, resolved by MIME type, and listed in the catalogue.

Testing

Fixture files for the test suite are stored in a Git submodule. After cloning this repository run:

git submodule update --init --recursive
composer install
composer test

The fixture corpus lives in the separate mime-detector-fixtures repository. Keeping the submodule means the fixtures are not bundled into Composer installs; Git source archives do not include submodule contents. Add new binary fixtures there and update the submodule reference when publishing a coordinated change.

Contributing

We welcome pull requests! Please review CONTRIBUTING for the coding standards and workflow. When adding new detections, include at least one fixture so behaviour can be verified automatically.

License

Released under the ISC License.

softcreatr / php-mime-detector

Package info

Security

Fund package maintenance!

Statistics