PHP Classes
elePHPant
Icontem

File: README.md

Recommend this page to a friend!
  Classes of Sascha Greuel  >  PHP MIME Type to Extension Detector  >  README.md  >  Download  
File: README.md
Role: Documentation
Content type: text/markdown
Description: Documentation
Class: PHP MIME Type to Extension Detector
Detect the type of a file analyzing its content
Author: By
Last change: Updated README
Updated README
Date: 7 months ago
Size: 5,923 bytes
 

Contents

Class file image Download

PHP Mime Detector Build Status Codeship Status for SoftCreatR/php-mime-detector

CodeFactor Codacy Badge codecov

Detecting the real type of a (binary) file doesn't have to be hard. Checking a file's extension is not reliable and can cause serious security issues.

This package helps you to determine the correct type of a file, by reading it byte for byte (up to 4096) and check for magic numbers#Magic_numbers_in_files).

However, this package isn't a replacement for any security software. It just aims to produce less false positives, than a simple extension check would produce.

A list of supported file types can be found on this Wiki page.

__Why a separate class?__

You may wonder, why we don't just rely on extensions like Fileinfo? First off all, a short background story:

We are building extensions and applications for an Open Source PHP Framework, thus we are creating web software for the masses. Many of our customers and/or users of our free products are on shared hosting without any possibility to install or manage installed PHP extensions. So our goal is to develop solutions with as few dependencies as necessary, but with as much functionality as possible.

While developing a solution, that allows people to convert HEIF/HEIC files to a more "standardized" format (using our own, external API), we had troubles detecting these files, because especially this format isn't known by most Webservers, yet. While checking the file extension isn't reliable, we had to find a reusable solution that works for most of our clients. So we started to build a magic number based check for these files. That was the birth of our Mime Detector.

__Why are the unit tests so poorly written?__

Short answer: I have just little experience in unit testing. This project was a good training and even if the unit tests could be better: I am proud of my progress :)

Demo

A demo (based on dev-master) can be found at WhatTheFile.info.

Requirements

If you are looking for a solution that works on older PHP versions (5.3.2+), head over to the oldphp branch.

Installation

Require this package using Composer, in the root directory of your project:

$ composer require softcreatr/php-mime-detector

Usage

Here is an example on how this package makes it very easy to determine the mime type (and it's corresponding file extension) of a given file:

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

// create an instance of the MimeDetector
$mimeDetector = new MimeDetector();

// set our file to read
try {
    $mimeDetector->setFile('foo.bar');
} catch (MimeDetectorException $e) {
    die('An error occured while trying to load the given file.');
}

// try to determine it's mime type and the correct file extension
$fileData = $mimeDetector->getFileType();

// print the result
echo '<pre>' . print_r($fileData, true) . '</pre>';

Or short:

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

try {
    echo '<pre>' . print_r((new MimeDetector())->setFile('foo.bar')->getFileType(), true) . '</pre>';
} catch (MimeDetectorException $e) {
    die('An error occured while trying to load the given file.');
}

Testing

Testing utilizes PHPUnit (what else?) by running this command:

$ composer test

However, you may check out a bunch of test files for a full test. Test files are no longer included in the composer package nor the Git repository itself, so you have to perform a checkout of this repository and install it's submodules:

$ git clone https://github.com/SoftCreatR/php-mime-detector
$ cd php-mime-detector
$ git submodule update --init --recursive

When done, perform a composer install and run PHPUnit as described above.

ToDo

  • Reduce method sizes, when 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

Contributing

Please see CONTRIBUTING for details.

When addding new detections, please make sure to provide at least one sample file.

License

License: LGPL v3

Free Software, Hell Yeah!

Support on BMC

Hey! Help us out with some cups of :coffee:!

BMC