feat: modularise MIME detection and document extension workflow

- replace the monolithic detector with a detection context, pipeline coordinator, and category-specific signature detectors that cache and return rich match objects
- harden the façade with guarded file handling, hash helpers, base64 URI fallbacks, and repository-driven MIME/extension lookups backed by a bi-directional map
- refresh the README with a clearer quick start, lookup examples, and a step-by-step guide for registering custom detectors and mappings
- add focused exception factories and byte-cache validation to signal unreadable files and support exhaustive test coverage
- add support for ~70 new file types

Author: SoftCreatR

.github/workflows/Test.yml

@@ -20,13 +20,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: [ '8.1', '8.2', '8.3', '8.4' ]
-    continue-on-error: ${{ matrix.php == '8.4' }}
+        php: [ '8.1', '8.2', '8.3', '8.4', '8.5' ]
+    continue-on-error: ${{ matrix.php == '8.5' }}
     name: PHP ${{ matrix.php }} Test
 
     steps:
       - name: Git checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Checkout submodules
         run: git submodule update --init --recursive
@@ -52,6 +52,6 @@ jobs:
         run: composer test -- --coverage-clover=coverage.xml
 
       - name: Run codecov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -1,97 +1,202 @@
 # PHP Mime Detector
 
-Detecting the real type of (binary) files doesn't have to be difficult. Checking a file's extension is not reliable and can lead to serious security issues.
+A modern, extensible MIME type detector for PHP that analyses the actual 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 so you can integrate it into security-sensitive workflows.
+
+## 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](https://github.com/SoftCreatR/php-mime-detector/wiki/Supported-file-types).
+- **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 external dependencies** – runs on any PHP 8.1+ installation without and can take
+  requiring additional, external extensions, or packages, but takes advantage
+  of `ZipArchive` when it is available.
 
-This package helps you determine the correct type of files by reading them byte by byte (up to 4096 bytes) and checking for [magic numbers](http://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files).
+## Installation
 
-However, this package isn't a replacement for any security software. It simply aims to produce fewer false positives than a simple extension check would.
+Install the package via Composer:
 
-A list of supported file types can be found on [this Wiki page](https://github.com/SoftCreatR/php-mime-detector/wiki/Supported-file-types).
+```bash
+composer require softcreatr/php-mime-detector
+```
 
-## Why a Separate Class?
+## Quick start
 
-You may wonder why we don't just rely on extensions like [Fileinfo](https://www.php.net/manual/en/book.fileinfo.php). Here's a brief background:
+Detecting the MIME type and the preferred extension for a file is as simple as
+instantiating the façade and calling its helpers:
 
-We develop extensions and applications for an Open Source PHP Framework, creating web software for the masses. Many of our customers and users of our free products are on shared hosting without any ability to install or manage PHP extensions. Therefore, our goal is to develop solutions with minimal dependencies while providing as much functionality as possible.
+```php
+<?php
 
-When developing a solution that allows people to convert HEIF/HEIC files to a more "standardized" format (using our own external API), we had trouble detecting these files because this format isn't widely recognized by most web servers. Since checking the file extension isn't reliable, we needed to find a reusable solution that works for most of our clients. This led to the creation of our Mime Detector, based on magic number checks.
+use SoftCreatR\MimeDetector\MimeDetector;
+use SoftCreatR\MimeDetector\MimeDetectorException;
 
-## Requirements
+require 'vendor/autoload.php';
 
-- PHP 8.1 or newer
-- [Composer](https://getcomposer.org)
+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 or unsupported formats.
+    echo $exception->getMessage();
+}
+```
 
-## Installation
+## Resolving MIME types and extensions
 
-Install this package using [Composer](https://getcomposer.org/) in the root directory of your project:
+The façade exposes several lookup helpers that do not require a file scan. They
+operate on the shared repository of known mappings:
 
-```bash
-composer require softcreatr/php-mime-detector
+```php
+$detector = new MimeDetector(__DIR__ . '/example.png');
+
+// Retrieve the canonical 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();
 ```
 
-## Usage
+Need a data URI? The detector will encode the configured file for you:
+
+```php
+$dataUri = $detector->getBase64DataURI();
+// data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
+```
+
+## Optional ZipArchive support
+
+The detector is fully functional without PHP's `ZipArchive` extension; all 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 other
+ZIP-based containers even when their identifying files live deeper inside the
+archive than the cached bytes.
+
+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.
+
+## Extending the detector
+
+Custom formats can be added without modifying the library itself. Follow these
+steps to teach the detector about a new signature and MIME mapping.
 
-Here is an example of how this package makes it easy to determine the MIME type and corresponding file extension of a given file:
+### 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
 <?php
 
-use SoftCreatR\MimeDetector\MimeDetector;
-use SoftCreatR\MimeDetector\MimeDetectorException;
+namespace App\MimeDetector;
 
-require 'vendor/autoload.php';
+use SoftCreatR\MimeDetector\Attribute\DetectorCategory;
+use SoftCreatR\MimeDetector\Contract\FileSignatureDetectorInterface;
+use SoftCreatR\MimeDetector\Detection\DetectionContext;
+use SoftCreatR\MimeDetector\Detection\MimeTypeMatch;
 
-try {
-    // Create an instance of MimeDetector with the file path
-    $mimeDetector = new MimeDetector('foo.bar');
-
-    // Get the MIME type and file extension
-    $fileData = [
-        'mime_type' => $mimeDetector->getMimeType(),
-        'file_extension' => $mimeDetector->getFileExtension(),
-        'file_hash' => $mimeDetector->getFileHash(),
-    ];
-
-    // Print the result
-    echo '<pre>' . print_r($fileData, true) . '</pre>';
-} catch (MimeDetectorException $e) {
-    die('An error occurred while trying to load the given file: ' . $e->getMessage());
+#[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;
+    }
 }
 ```
 
-## Testing
+### 2. Register MIME mappings
 
-This project uses PHPUnit for testing. To run tests, use the following command:
+Extend the repository so your MIME type resolves to the expected extension(s):
 
-```bash
-composer test
+```php
+use SoftCreatR\MimeDetector\MimeTypeRepository;
+
+$repository = MimeTypeRepository::createDefault();
+$repository->register('custom', 'application/x-custom');
 ```
 
-To run a full test suite, you can use a set of provided test files. These files are not included in the Composer package or Git repository, so you must clone this repository and initialize its submodules:
+### 3. Compose a detector pipeline
 
-```bash
-git clone https://github.com/SoftCreatR/php-mime-detector
-cd php-mime-detector
-git submodule update --init --recursive
+Finally, plug your detector into the default pipeline and hand both pieces to
+the façade. Placing your detector first ensures it runs before the built-in
+matchers:
+
+```php
+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);
 ```
 
-After that, install the necessary dependencies with `composer install`, and run PHPUnit as described above.
+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.
 
-## ToDo
+## Testing
 
-- Reduce method sizes where possible.
-- Add a method that accepts a MIME type and returns the corresponding file extension.
-- Add a method that accepts a file extension and returns a list of corresponding MIME types.
-- Add a method that returns a list of all detectable MIME types and their corresponding file extensions.
+Fixture files for the test suite are stored in a Git submodule. After cloning
+this repository run:
 
-## Contributing
+```bash
+git submodule update --init --recursive
+composer install
+composer test
+```
 
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
+## Contributing
 
-When adding new detections, please provide at least one sample file to ensure the detection works as expected.
+We welcome pull requests! Please review [CONTRIBUTING](CONTRIBUTING.md) for the
+coding standards and workflow. When adding new detections, include at least one
+fixture so behaviour can be verified automatically.
 
 ## License
 
-[ISC License](LICENSE.md)
-
-Free Software, Hell Yeah!
+Released under the [ISC License](LICENSE.md).

composer.json

@@ -1,15 +1,15 @@
 {
   "name": "softcreatr/php-mime-detector",
-  "description": "Mime Detector Decoder",
+  "description": "Modern, extensible MIME type detector for PHP",
+  "license": "ISC",
   "keywords": [
     "Mime",
     "Mime Type",
     "File Type",
-    "Magic Number"
+    "Magic Number",
+    "Detector",
+    "Extension Lookup"
   ],
-  "homepage": "https://1-2.dev",
-  "version": "4.0.0",
-  "license": "ISC",
   "authors": [
     {
       "name": "Sascha Greuel",
@@ -20,19 +20,23 @@
       "email": "[email protected]"
     }
   ],
+  "homepage": "https://1-2.dev",
+  "support": {
+    "email": "[email protected]",
+    "issues": "https://github.com/SoftCreatR/php-mime-detector/issues",
+    "source": "https://github.com/SoftCreatR/php-mime-detector"
+  },
   "require": {
-    "php": ">=8.1.0"
+    "php": ">=8.1.0",
+    "ext-ctype": "*"
   },
   "require-dev": {
     "phpunit/phpunit": ">=10.0",
     "roave/security-advisories": "dev-latest",
-    "squizlabs/php_codesniffer": "^3.7"
-  },
-  "config": {
-    "optimize-autoloader": true,
-    "preferred-install": "dist",
-    "sort-packages": true
+    "squizlabs/php_codesniffer": "^3.10"
   },
+  "minimum-stability": "stable",
+  "prefer-stable": true,
   "autoload": {
     "psr-4": {
       "SoftCreatR\\MimeDetector\\": "src/SoftCreatR/MimeDetector"
@@ -43,16 +47,14 @@
       "SoftCreatR\\Tests\\MimeDetector\\": "tests/SoftCreatR/MimeDetector"
     }
   },
-  "minimum-stability": "stable",
-  "prefer-stable": true,
+  "config": {
+    "optimize-autoloader": true,
+    "preferred-install": "dist",
+    "sort-packages": true
+  },
   "scripts": {
     "cs-check": "phpcs",
     "cs-fix": "phpcbf",
     "test": "phpunit"
-  },
-  "support": {
-    "email": "[email protected]",
-    "issues": "https://github.com/SoftCreatR/php-mime-detector/issues",
-    "source": "https://github.com/SoftCreatR/php-mime-detector"
   }
 }

src/SoftCreatR/MimeDetector/Attribute/DetectorCategory.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SoftCreatR\MimeDetector\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to group signature detectors by a logical category.
+ *
+ * The category metadata can be used by consumers to build reporting or
+ * filtering logic around the shipped signature detectors.
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+final class DetectorCategory
+{
+    public function __construct(public readonly string $name)
+    {
+        // ...
+    }
+}