README

FInfo (расшифровывается как Fileinfo - информация о файле) - расширяемый пакет для извлечения сведений из метаданных файла и/или на основе контента файла.

Изначально FInfo разработан для Dios CMS, но может независимо использоваться в любом PHP-проекте.

Что может FInfo?

По умолчанию пакет имеет минимальные возможности для работы с файлами (может извлечь минимум информации из файла).

Пакет используется для предоставления единого интерфейса для извлечения сведений из файлов с разными MIME-типами. Поэтому для работы с конкретными свойствами или типами файлов необходимо устанавливать или разрабатывать собственные классы или пакеты, затем подключать их с помощью методов класса в Fileinfo.

Класс Fileinfo

Класс Fileinfo предоставляет набор методов для работы с классами-обработчиками (классы извлекающие данные из файлов) и набор методов для извлечения информации из файлов.

В таблице перечислены основные методы класса. Более подробная информация содержится в самих классах.

Метод класса	Описание
addClass($className)	Добавляет указанный класс в список классов-обработчиков. Добавляемый класс должен быть расширен классом FileExplorer.
getClasses()	Возвращает список добавленных классов.
file($filename, $virtualProperties = null)	Возвращает сведения о файле. Если в параметре $virtualProperties указан список виртуальных свойств, то будут возвращены указанные виртуальные свойства.
getFileinfo($filename, $virtualProperty)	Возвращает информацию конкретного виртуального свойства указанного файла.

Как использовать FInfo?

Установите FInfo через composer (хранилище Packagist) или сделав клон с репозитория Github.

Fileinfo работает со статическими методами, поэтому вы можете не инициализировать класс, и добавлять и извлекать данные из файлов в любом месте, где доступен подключенный класс.

// Подключите основной класс Fileinfo и классы-обработчики
use Belca\FInfo\Fileinfo; // Основной
use Belca\FInfo\BasicFileinfo; // Базовый класс-обработчик

...

// Добавьте классы-обработчики в список обработчиков
Fileinfo::addClass(BasicFileinfo::class);

...

// Извлеките всю информацию о файле
Fileinfo::file($filename);

// Output:
// [
//     [created] => 1531556313
//     [edited] => 1531556313
//     [size] => 9399
//     [filesize] => 9399
// ]

// Получите информацию о конкретных виртуальных свойствах
Fileinfo::file($filename, ['created', 'size');

// Output:
// [
//     [created] => 1531556313
//     [size] => 9399
// ]

// Если вы укажите несуществующее виртуальное свойство, то ошибок не будет. Свойство не будет возвращено.
Fileinfo::file($filename, ['created', 'edited', 'size', 'length');

// Output:
// [
//     [created] => 1531556313
//     [edited] => 1531556313
//     [size] => 9399
//     [filesize] => 9399
// ]

// Получите информацию только об одном виртуальном свойстве
Fileinfo::getFileinfo($filename, 'size');

// Output: 9399

// Или    
Fileinfo::file($filename, ['size']);

// Output:
// [
//     [size] => 9399
// ]

// Или
Fileinfo::file($filename, 'size');

// [
//     [size] => 9399
// ]

Расширение Fileinfo и FileExplorer

Как вы можете догадываться, и как упоминалось выше, пакет легко расширяется и дополняется другими обработчиками виртуальных свойств.

Вы можете посмотреть исходный код класса BasicFileinfo. Он достаточно простой и хорошо показывает как создать новый класс-обработчик для извлечения виртуальных свойств.

// Используйте абстрактный класс для создания нового обработчика
use Belca\FInfo\FileExplorer;

class ImageColorFileinfo extends FileExplorer
{

// При необходимости, вы можете задать алиасы существующих виртуальных свойств или указать используемые методы извлечения виртуального свойства
protected static $aliases = [
    'humanColor' => 'color',
    // or
    'colorForHuman' => 'getColorProperty',
];

// Если обработчик работает только с определенными типами данных, то их можно перечислить в $mimes;
protected static $mimes => ['image/png', 'image/jpeg'];

// Реализуйте метод проверки совместимости с файлом
public function checkCompatibility()
{
    // Код проверяющий возможность обработки файла
    // При успешной проверке верните true.
    // Если обработчик работает со всеми типами файлов, то также верните true, желательно проверив существование файла в этом методе или в методе извлекающим виртуальное свойство файла

    return true;
}

// Добавьте необходимые "извлекаторы" (методы извлекающие свойства файла) в класс
public function getColorProperty()
{
    if ($this->checkCompatibility() {
        // Код метода с возвращением полученного значения

        return $color;
    }

    // При неудачной обработке или проверки совместимости верните false

    return false;
}

Как видно, реализовать собственного обработчика действительно просто, нужно только разместить код обрабатывающий файл и извлекающий свойства файла.

Подключите реализуемый класс в место добавления класса-обработчика и добавьте его в класс Fileinfo с помощью метода addClass.

use Belca\FInfo\Fileinfo; // Основной
use Belca\FInfo\ImageColorFileinfo; // Класс извлекающий цвет из изображения

...

// Добавляем в список обработчиков файла
Fileinfo::addClass(ImageColorFileinfo::class);

Определения FInfo

Для более понятной работы с пакетом FInfo были введены некоторые абстрактные понятия.

Виртуальные свойства, методы извлечения, алиасы и значения

Для получения информации о файле (свойств файла) используются виртуальные свойства, алиасы и методы извлечения.

Виртуальные свойства и параметры файлов (они же вычисленные свойства и высчитанные значения) — понятия введенные в этом пакете для определения получаемых значений и свойств файла. Виртуальное значение может быть получено из существующих данных файла (например, размер файла, дата изменения файла, владелец файла и т.п.) или определено на основе содержимого файла.

На самом деле, виртуальное свойство - название метода класса для получения значения свойства файла измеряемое одним значением или набором значений (массивом), а виртуальное значение - рассчитанное или извлеченное значение на основе данных файла и возвращаемое определенным методом (виртуальным свойством).

Примеры виртуальных значений

Примерами виртуальных свойств будут:

средний цвет изображения для человека;
основные цвета изображения;
создатель файла (изображения, аудиотрека, видеофайла и т.п.);
координаты места создания фотографии;
размер файла;
длительность файла (аудиофайла, видеофайла, анимации);
дата создания файла и т.д.

Как можно заменить, такие значения как размер файла, геолокация, создатель файла и т.п. могут быть определены в метаданных файла или в сведениях самого файла, а значение свойств как средний цвет изображения, основные цвета изображения и т.п., отсутствуют у файлов и для их получения необходимо обработать файл с помощью специальных инструментов (библиотек, модулей, классов и т.п.).

Лицензия

Пакет распространяется по лицензии MIT.

belca / finfo

Maintainers

Details