README

A PHP library for managing file resources, inspecting file metadata, and detecting MIME types from file content.

The package provides a File abstraction combining file resource information with MIME type detection.

Unlike extension-based detection, MIME type detection relies on the actual file content and multiple detection strategies.

Requirements

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

Installation

Install the package using Composer:

composer require moudarir/file

File

File is the main entry point of the library.

It provides access to:

the file resource and its metadata through FileResource;
MIME type detection through MimeDetection.

<?php

use Moudarir\File\File;
use Moudarir\File\Exceptions\FileResourceException;
use Moudarir\File\Exceptions\MimeDetectionException;

require_once 'vendor/autoload.php';

try {
    $file = File::create('/path/to/document.pdf');

    $resource = $file->resource();
    $detection = $file->detection();

    echo $detection->mimeTypeValue() . PHP_EOL;
    echo $detection->detectorValue() . PHP_EOL;

    echo $resource->filesize() . PHP_EOL;
    echo $resource->lastModified() . PHP_EOL;
    echo $resource->dirname() . PHP_EOL;
    echo $resource->basename() . PHP_EOL;
    echo $resource->filename() . PHP_EOL;
    echo $resource->extension() . PHP_EOL;
} catch (FileResourceException|MimeDetectionException $exception) {
    echo $exception->getMessage();
}

File Resource

FileResource represents an existing readable file and exposes its main resource information.

File path

$resource->filepath();

Stream

$resource->stream();

The stream is opened when the FileResource is created and remains owned by the FileResource.

File size

$resource->filesize();

The file size is resolved when the resource is created.

Last modified

$resource->lastModified();

Header

The first bytes of the file can be retrieved with:

$resource->firstBytes();

The same content can be represented as hexadecimal:

$resource->hexHeader();

Path information

$resource->dirname();
$resource->basename();
$resource->filename();
$resource->extension();

MIME Detection

MIME type detection is exposed through MimeDetection:

$detection = $file->detection();

MIME type

$detection->mimeType();
$detection->mimeTypeValue();

mimeType() returns the MimeType enum while mimeTypeValue() returns its MIME string value.

Detector source

$detection->detector();
$detection->detectorValue();

detector() returns the DetectorSource enum while detectorValue() returns its string value.

Manually Provided MIME Type

MIME type detection can be skipped when the MIME type is already known:

use Moudarir\File\Enum\MimeType;

$file = File::create('/path/to/file.pdf', MimeType::PDF);

In this case, the detection source is:

DetectorSource::NOT_SET

with the value:

manually_provided

No MIME detection strategy is executed.

MIME type Detection Process

The detection pipeline follows a strict order:

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

Each detector returns:

a MIME type and its detector source when it recognizes the file;
null when it cannot identify the file.

The first successful detection is used to create the resulting MimeDetection object.

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

Disk Images

ISO 9660
Apple Disk Image (DMG)

Text Formats

The library detects common text-based formats:

PHP
JSON
XML
HTML
SVG
CSS
JavaScript
Markdown
YAML
SQL

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

Separated Values

Separated values are detected by analyzing the structure of the file rather than its extension.

Example

The following example detects a PDF file and displays the MIME type, detector source and file metadata:

<?php

use Moudarir\File\Exceptions\FileResourceException;
use Moudarir\File\Exceptions\MimeDetectionException;
use Moudarir\File\File;

require_once 'vendor/autoload.php';

try {
    $file = File::create('/path/to/document.pdf');

    $resource = $file->resource();
    $detection = $file->detection();

    echo '<div style="margin-bottom: 20px;">';
    echo '<h4 style="margin-bottom: 10px;">Mime Type</h4>';
    echo '<pre>';
    var_dump(
        $detection->mimeType(),
        $detection->mimeTypeValue()
    );
    echo '</pre>';
    echo '</div>';

    echo '<div style="margin-bottom: 20px;">';
    echo '<h4 style="margin-bottom: 10px;">Detector</h4>';
    echo '<pre>';
    var_dump(
        $detection->detector(),
        $detection->detectorValue()
    );
    echo '</pre>';
    echo '</div>';

    echo '<div style="margin-bottom: 20px;">';
    echo '<h4 style="margin-bottom: 10px;">Metadata</h4>';
    echo '<pre>';
    var_dump(
        $resource->filesize(),
        $resource->lastModified(),
        $resource->dirname(),
        $resource->basename(),
        $resource->filename(),
        $resource->extension(),
    );
    echo '</pre>';
    echo '</div>';
} catch (FileResourceException|MimeDetectionException $exception) {
    error_log($exception->getMessage());
}

Example output:

Mime Type

enum(Moudarir\File\Enum\MimeType::PDF)
string(15) "application/pdf"

Detector

enum(Moudarir\File\Enum\DetectorSource::MAGIC_NUMBER)
string(12) "magic_number"

Metadata

int(...)
int(...)
string(...) "/path/to"
string(12) "document.pdf"
string(8) "document"
string(3) "pdf"

Design Principles

Content over extension

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

For example, a file named:

image.jpg

containing a PDF document can be detected as:

application/pdf

Detection is based on the file content and the available detection strategies.

Performance Considerations

The library includes several optimizations:

preload of the file header;
caching of the hexadecimal header representation;
caching of file metadata;
stopping detection as soon as a detector succeeds;
avoiding ZIP parsing unless the file has a ZIP signature.

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;
application security policies.

It only identifies the file format based on the available detection strategies.

License

MIT License

moudarir / file

Maintainers

Package info

Statistics

Security