PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

$detector = finfo_open(FILEINFO_MIME_TYPE);
if ($detector === false) { throw new RuntimeException('Не подготовить определитель'); }
$text = "Pickup order 104\n";
echo 'Памятка: ', $text;
echo 'Формат: ', $detector->buffer($text), "\n";

Памятка: Pickup order 104
Формат: text/plain

Объект хранит базу правил и выбранный формат ответа. finfo_open может вернуть false; new finfo при ошибке конструктора бросает исключение, поэтому сравнение созданного объекта с false не нужно.

<?php
declare(strict_types=1);

$detector = finfo_open(FILEINFO_MIME_TYPE);
if ($detector === false) { throw new RuntimeException('Не подготовить определитель'); }
foreach (['pickup.txt', 'instructions.html'] as $name) {
    $type = $detector->file(__DIR__ . '/' . $name);
    if ($type === false) { throw new RuntimeException('Не определить тип'); }
    echo $name, ': ', $type, "\n";
}

pickup.txt: text/plain
instructions.html: text/html

Определитель создаётся до цикла и используется повторно. Каждый вызов всё равно анализирует содержимое. Текстовая памятка и HTML-инструкция требуют разных способов показа: HTML нельзя безусловно вставлять как доверенную разметку.

<?php
declare(strict_types=1);

$warned = false;
set_error_handler(static function (int $level) use (&$warned): bool {
    if ($level !== E_WARNING) { return false; }
    $warned = true;
    return true;
});
try { $detector = finfo_open(FILEINFO_MIME_TYPE, __DIR__ . '/missing.magic'); }
finally { restore_error_handler(); }
if ($detector === false) { echo "Проверка документов недоступна: база типов не загружена.\n"; }
if ($warned) { echo "Файловое предупреждение получено; нужна проверка настройки сервера.\n"; }

Проверка документов недоступна: база типов не загружена.
Файловое предупреждение получено; нужна проверка настройки сервера.

Отсутствует именно настроенная база, а не пользовательский документ. Не подменяйте отказ сервиса ответом «разрешённый формат». Handler показан только для контролируемого опыта и сразу восстановлен.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$text = "Pickup order 104\n";
echo 'Памятка: ', $text;
echo 'Формат: ', $detector->buffer($text), "\n";

Памятка: Pickup order 104
Формат: text/plain

Объект хранит базу правил и выбранный формат ответа. finfo_open может вернуть false; new finfo при ошибке конструктора бросает исключение, поэтому сравнение созданного объекта с false не нужно.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
foreach (['pickup.txt', 'instructions.html'] as $name) {
    $type = $detector->file(__DIR__ . '/' . $name);
    if ($type === false) { throw new RuntimeException('Не определить тип'); }
    echo $name, ': ', $type, "\n";
}

pickup.txt: text/plain
instructions.html: text/html

Определитель создаётся до цикла и используется повторно. Каждый вызов всё равно анализирует содержимое. Текстовая памятка и HTML-инструкция требуют разных способов показа: HTML нельзя безусловно вставлять как доверенную разметку.

<?php
declare(strict_types=1);

try { new finfo(FILEINFO_MIME_TYPE, 'missing.magic'); }
catch (Exception $error) { echo "Cannot load configured database\n"; }

Cannot load configured database

Конструктор не возвращает false. Это отказ конфигурации сервиса, а не сообщение посетителю о плохом файле.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$type = finfo_file($detector, 'document.jpg');
if ($type === false) { throw new RuntimeException('Cannot detect type'); }
echo $type, "\n";

text/plain

Файл назван .jpg, но его содержимое — текст. Имя не превратило его в изображение; MIME-тип остаётся эвристическим результатом, не полным разбором формата.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
echo finfo_file($detector, 'document.jpg', FILEINFO_MIME_ENCODING), "\n";
echo finfo_file($detector, 'document.jpg'), "\n";
echo finfo_file($detector, 'document.jpg', FILEINFO_NONE), "\n";

us-ascii
text/plain
text/plain

Второй и третий результаты показывают, что временный режим не остался у объекта. Переданный 0 не сбрасывает его в описательный режим.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
try { $type = finfo_file($detector, "bad\0path"); }
catch (ValueError $error) { echo "Invalid path\n"; }

Invalid path

Пример рассчитан на PHP 8.5+. Нулевой байт отвергнут до открытия; раньше этот случай имел TypeError. Не убирайте такой байт молча, превращая исходное имя в другой путь.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$contents = "Pickup order 104\n";
$type = finfo_buffer($detector, $contents);
if ($type === false) { throw new RuntimeException('Не определить тип'); }
echo 'Данные: ', $contents;
echo 'Формат: ', $type, "\n";

Данные: Pickup order 104
Формат: text/plain

buffer анализирует сами байты строки. Передача "pickup.txt" означала бы анализ букв имени, а не открытие файла. Для файла, который ещё лежит на диске, выбирайте file.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
echo finfo_buffer($detector, "Hello world\n", FILEINFO_MIME_ENCODING), "\n";
echo finfo_buffer($detector, "Hello world\n"), "\n";
echo finfo_buffer($detector, "Hello world\n", FILEINFO_NONE), "\n";

us-ascii
text/plain
text/plain

Второй и третий результаты показывают, что временный режим не остался у объекта. Переданный 0 не сбрасывает его в описательный режим.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$bytes = hex2bin('47494638396101000100800000000000ffffff21f90401000000002c00000000010001000002024401003b');
if ($bytes === false) { throw new RuntimeException('Invalid fixed fixture'); }
echo finfo_buffer($detector, $bytes), "\n";
echo finfo_buffer($detector, base64_encode($bytes)), "\n";

image/gif
text/plain

GIF — небольшой собственный бинарный fixture. Base64 — уже другой набор текстовых байтов. Декодирование внешнего Base64 выполняют строго и с ограничением размера; результат MIME не заменяет полноценное декодирование изображения.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$contents = "Pickup order 104\n";
$type = $detector->buffer($contents);
if ($type === false) { throw new RuntimeException('Не определить тип'); }
echo 'Данные: ', $contents;
echo 'Формат: ', $type, "\n";

Данные: Pickup order 104
Формат: text/plain

buffer анализирует сами байты строки. Передача "pickup.txt" означала бы анализ букв имени, а не открытие файла. Для файла, который ещё лежит на диске, выбирайте file.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
echo $detector->buffer("Hello world\n", FILEINFO_MIME_ENCODING), "\n";
echo $detector->buffer("Hello world\n"), "\n";
echo $detector->buffer("Hello world\n", FILEINFO_NONE), "\n";

us-ascii
text/plain
text/plain

Второй и третий результаты показывают, что временный режим не остался у объекта. Переданный 0 не сбрасывает его в описательный режим.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$bytes = hex2bin('47494638396101000100800000000000ffffff21f90401000000002c00000000010001000002024401003b');
if ($bytes === false) { throw new RuntimeException('Invalid fixed fixture'); }
echo $detector->buffer($bytes), "\n";
echo $detector->buffer(base64_encode($bytes)), "\n";

image/gif
text/plain

GIF — небольшой собственный бинарный fixture. Base64 — уже другой набор текстовых байтов. Декодирование внешнего Base64 выполняют строго и с ограничением размера; результат MIME не заменяет полноценное декодирование изображения.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$text = "Pickup order 104\n";
echo 'Тип: ', $detector->buffer($text), "\n";
finfo_set_flags($detector, FILEINFO_MIME_ENCODING);
echo 'Кодировка: ', $detector->buffer($text), "\n";

Тип: text/plain
Кодировка: us-ascii

set_flags заменяет постоянный режим объекта. Данные $text не перекодируются: изменился вопрос, на который отвечает определитель.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
finfo_set_flags($detector, FILEINFO_MIME_TYPE | FILEINFO_MIME_ENCODING);
echo $detector->buffer("Привет\n"), "\n";

text/plain; charset=utf-8

Оператор | объединяет битовые флаги. FILEINFO_MIME — готовая константа той же комбинации. Для точного списка допустимых MIME удобнее MIME_TYPE, иначе charset станет частью сравниваемой строки.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$text = "Pickup order 104\n";
finfo_set_flags($detector, FILEINFO_NONE);
echo 'Описание: ', $detector->buffer($text), "\n";
finfo_set_flags($detector, FILEINFO_MIME_TYPE);
echo 'Для сравнения форматов: ', $detector->buffer($text), "\n";

Описание: ASCII text
Для сравнения форматов: text/plain

Точная свободная формулировка описания зависит от libmagic; здесь показан фактический результат учебного runtime. Для списка допустимых форматов используют стабильнее выраженный MIME_TYPE, а не сравнивают полное описание.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$text = "Pickup order 104\n";
echo 'Тип: ', $detector->buffer($text), "\n";
$detector->set_flags(FILEINFO_MIME_ENCODING);
echo 'Кодировка: ', $detector->buffer($text), "\n";

Тип: text/plain
Кодировка: us-ascii

set_flags заменяет постоянный режим объекта. Данные $text не перекодируются: изменился вопрос, на который отвечает определитель.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$detector->set_flags(FILEINFO_MIME_TYPE | FILEINFO_MIME_ENCODING);
echo $detector->buffer("Привет\n"), "\n";

text/plain; charset=utf-8

Оператор | объединяет битовые флаги. FILEINFO_MIME — готовая константа той же комбинации. Для точного списка допустимых MIME удобнее MIME_TYPE, иначе charset станет частью сравниваемой строки.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$text = "Pickup order 104\n";
$detector->set_flags(FILEINFO_NONE);
echo 'Описание: ', $detector->buffer($text), "\n";
$detector->set_flags(FILEINFO_MIME_TYPE);
echo 'Для сравнения форматов: ', $detector->buffer($text), "\n";

Описание: ASCII text
Для сравнения форматов: text/plain

Точная свободная формулировка описания зависит от libmagic; здесь показан фактический результат учебного runtime. Для списка допустимых форматов используют стабильнее выраженный MIME_TYPE, а не сравнивают полное описание.

<?php
declare(strict_types=1);

$reflection = new ReflectionFunction('finfo_close');
$attributes = $reflection->getAttributes(Deprecated::class);
echo $attributes[0]->newInstance()->since, "\n";

8.5

Это пример PHP 8.5 с метаданными. Он не вызывает устаревшую функцию и не подавляет предупреждение; на старом PHP атрибута может не быть.

<?php
declare(strict_types=1);

function detectDocumentType(string $text): string
{
    $detector = new finfo(FILEINFO_MIME_TYPE);
    $type = $detector->buffer($text);
    if ($type === false) { throw new RuntimeException('Не определить тип'); }
    return $type;
}
echo 'Памятка заказа 104: ', detectDocumentType("Pickup order 104\n"), "\n";

Памятка заказа 104: text/plain

После возврата локальная ссылка $detector исчезает, объект освобождается, если его больше никто не удерживает. finfo_close не нужен в PHP8.1+ и deprecated с8.5. Явный unset после каждого файла тоже не обязателен.

<?php
declare(strict_types=1);

$mime = mime_content_type('report.txt');
if ($mime === false) { throw new RuntimeException('Cannot detect type'); }
echo $mime, "\n";

text/plain

Здесь нет загрузки от посетителя: report.txt — собственный учебный файл. Для формы нужен tmp_name после проверки структуры $_FILES и кода загрузки.

<?php
declare(strict_types=1);

$stream = fopen('php://temp', 'w+b');
if ($stream === false) { throw new RuntimeException('Cannot open temporary stream'); }
try {
    fwrite($stream, "Hello world\n");
    fseek($stream, 3);
    echo mime_content_type($stream), "\n";
    echo ftell($stream), "\n";
} finally { fclose($stream); }

text/plain
3

После распознавания собственный поток остался на позиции 3. Это проверка конкретного перематываемого потока; она не означает поддержку такой семантики у любого ресурса/URL.

<?php
declare(strict_types=1);

$types = new finfo(FILEINFO_MIME_TYPE);
$encoding = new finfo(FILEINFO_MIME_ENCODING);
$contents = "Hello world\n";
echo $types->buffer($contents), "\n", $encoding->buffer($contents), "\n";

text/plain
us-ascii

Первый результат отвечает «какой формат», второй — «какая предполагается кодировка». Ни одна операция не перекодировала contents.

<?php
declare(strict_types=1);

$detector = new finfo(FILEINFO_MIME_TYPE);
$same = $detector;
$same->set_flags(FILEINFO_MIME_ENCODING);
echo $detector->buffer("Hello world\n"), "\n";
var_dump($same === $detector);

us-ascii
bool(true)

Изменение видно через обе переменные, потому что объект один. Чтобы соседние операции не меняли друг другу политику, передавайте временный флаг на вызов или создайте отдельные объекты.