README

A PHP library for detecting the real MIME type of files by analyzing their content.

Unlike extension-based detection, this library relies on multiple detection strategies:

binary signatures (magic numbers);
ZIP container analysis;
text format inspection;
ISO Base Media analysis (MP4, MOV, AVIF, HEIC...);
RIFF container analysis (WEBP, WAV, AVI...);
PHP FileInfo/libmagic fallback.

The goal is to provide a reliable MIME type detection based on the actual file content.

Requirements

PHP >= 8.4
fileinfo extension
zip extension for ZIP container analysis

Optional:

exif extension for additional image format detection.

Installation

Install the package using Composer:

composer require moudarir/mime-detector

Basic Usage

use Moudarir\MimeDetector\Exceptions\MimeTypeException;
use Moudarir\MimeDetector\MimeType;

try {
    $result = MimeType::detect('/path/to/file.pdf');
    echo $result->mimeValue();
} catch (MimeTypeException $exception) {
    echo $exception->getMessage();
}

Output:

application/pdf

You can also retrieve which detector identified the file:

echo $result->detector();

Example output:

Moudarir\MimeDetector\Detector\MagicNumberMimeDetector

Detection Process

The detection pipeline follows a strict order:

ZIP Container
      ↓
Magic Number Detection
      ↓
Text Detection
      ↓
FileInfo/libmagic
      ↓
application/octet-stream fallback

Each detector returns:

a DetectionResult when it recognizes the file;
null when it cannot identify it.

The first successful detection is returned.

Supported Formats

Images

JPEG
PNG
GIF
BMP
TIFF
WEBP
AVIF
HEIC
HEIF
ICO
SVG

Documents

PDF
DOCX
XLSX
PPTX
ODT
ODS
ODP
EPUB

ZIP-based Containers

The library can identify specialized ZIP containers by inspecting their internal structure.

Microsoft Office Open XML

DOCX
XLSX
PPTX

OpenDocument

Other containers

EPUB
APK
JAR

Detection is based on the internal ZIP structure, not the file extension.

Audio

MP3
FLAC
OGG
WAV
M4A

Video

MP4
MOV
AVI
Matroska
WebM
3GP

Executables

ELF
Windows PE

Text Formats

The library detects common text-based formats:

PHP
JSON
XML
HTML
SVG
CSS
JavaScript
Markdown
YAML
SQL
CSV
TSV

Generic text files are handled by PHP FileInfo when no specialized format is detected.

Example

Detecting a DOCX file:

use Moudarir\MimeDetector\Exceptions\MimeTypeException;
use Moudarir\MimeDetector\MimeType;

try {
    $result = MimeType::detect('/path/to/file.pdf');
    echo $result->mimeValue();
    echo PHP_EOL;
    echo $result->detector();
} catch (MimeTypeException $exception) {
    echo $exception->getMessage();
}

Output:

application/vnd.openxmlformats-officedocument.wordprocessingml.document

Moudarir\MimeDetector\Detector\ZipMimeDetector

Design Principles

Content over extension

The file extension is never used as the primary source of truth.

Example:

A file named:

image.jpg

containing a PDF document will be detected as:

application/pdf

Performance Considerations

The library includes several optimizations:

lazy loading of file headers;
caching of binary header data;
caching of hexadecimal header representation;
stopping detection as soon as a detector succeeds;
avoiding ZIP parsing unless the file is identified as a ZIP archive.

Limitations

MIME detection is not a complete security validation mechanism.

A file can have a valid MIME type while still containing malicious content.

This library should not replace:

antivirus scanning;
application-level validation;
security policies.

It only identifies the actual file format.

License

MIT License

moudarir / mime-detector

Maintainers

Package info

Statistics

Security