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

PHP 5.1.2+ · hash

hash(string $algo, string $data, bool $binary = false, array $options = []): string

Заметить изменение номера заказа. В hash('sha256', $text) первый аргумент выбирает алгоритм, второй задаёт точные байты. Возвращается строка отпечатка; исходный текст не меняется. === сравнивает и значение, и тип.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Получить воспроизводимый отпечаток уже имеющейся строки.

<?php
declare(strict_types=1);

$original = 'order=42';
$trusted = hash('sha256', $original);
echo 'Отпечаток order=42: ', $trusted, "\n";
$received = 'order=43';
echo $trusted === hash('sha256', $received) ? "Заказ не изменён.\n" : "Заказ изменён; импорт остановлен.\n";

Отпечаток order=42: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705
Заказ изменён; импорт остановлен.

Версия преобразования включена в ключ, иначе изменение настроек оставит прежний кэш. Фиксированный namespace с разделителем и фиксированным hex-хвостом однозначен. Для нескольких произвольных полей нельзя просто склеить строки: пары ab+c и a+bc совпадут; сначала задают однозначное кодирование полей.

<?php
declare(strict_types=1);

$content = 'demo image bytes';
$pipeline = 'thumbnail-v2';
$key = $pipeline . ':' . hash('sha256', $content);
$same = $pipeline . ':' . hash('sha256', $content);
$next = 'thumbnail-v3:' . hash('sha256', $content);
echo str_starts_with($key, 'thumbnail-v2:') ? 'versioned' : 'bad';
echo "\n";
var_dump($key === $same, $key !== $next);

versioned
bool(true)
bool(true)

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

<?php
declare(strict_types=1);

try {
    hash('sha-unknown', 'abc');
} catch (ValueError $error) {
    echo 'invalid algorithm';
}

invalid algorithm

Ошибки и ограничения. Неизвестный algo вызывает ValueError с PHP 8; раньше были warning и false. options добавлен в 8.1, неверные типы настроек некоторых алгоритмов deprecated с 8.4. См. точные правила options. Быстрый digest не заменяет парольный алгоритм и не скрывает содержание.

Продолжить: hash_file, hash_init, hash_hmac. Как выбрать задачу и алгоритм.

• PHP: hash

PHP 5.1.2+ · hash

hash_algos(): array

Проверить алгоритм перед проверкой экспорта. Список hash_algos отражает возможности текущего процесса, включая алгоритмы, которые не предназначены для защиты. Наличие имени не означает, что его разрешила политика сервиса. Выбираем sha256 явно и отказываем при отсутствии.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Узнать алгоритмы, реально зарегистрированные в текущем PHP.

<?php
declare(strict_types=1);

if (!in_array('sha256', hash_algos(), true)) { throw new RuntimeException('Нет обязательного sha256'); }
echo "Проверка экспорта: sha256 доступен.\n";
echo 'Контрольный результат: ', hash('sha256', 'order=42'), "\n";

Проверка экспорта: sha256 доступен.
Контрольный результат: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705

Расширение может поддерживать устаревший алгоритм для совместимости. Политика сервиса определяется отдельно; переключение алгоритма, если оно вообще нужно протоколу, должно входить в защищённые параметры.

<?php
declare(strict_types=1);

$allowed = ['sha256', 'sha512'];
$available = hash_algos();
foreach (['sha256', 'md5'] as $requested) {
    $ok = in_array($requested, $allowed, true)
        && in_array($requested, $available, true);
    echo $requested, ':', $ok ? 'allowed' : 'rejected', "\n";
}

sha256:allowed
md5:rejected

Ошибки и ограничения. Нет параметров конфигурации и специального значения false. Ветки SHA-3/sha512 truncation добавлены в 7.1, crc32c в 7.4, Murmur/xxHash в 8.1. Список алгоритмов текущей версии перечислен в таблице семейств.

Продолжить: hash_hmac_algos, hash. Как выбрать задачу и алгоритм.

• PHP: hash_algos

PHP 5.1.2+ · hash

hash_file(string $algo, string $filename, bool $binary = false, array $options = []): string|false

Проверить содержимое полученной выгрузки. Файл export.txt приложен: две строки order=42 и qty=2, каждая заканчивается LF. hash_file читает его содержимое, не имя. Путь __DIR__ задаёт каталог example.php.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Прочитать локальный файл потоково и вычислить отпечаток содержимого.

<?php
declare(strict_types=1);

$expected = 'c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987';
$actual = hash_file('sha256', __DIR__ . '/export.txt');
if ($actual === false) { throw new RuntimeException('Выгрузка не прочитана'); }
echo 'export.txt: ', $actual, "\n";
echo hash_equals($expected, $actual) ? "Заказ42, количество2: файл соответствует манифесту.\n" : "Импорт запрещён: файл изменён.\n";

export.txt: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987
Заказ42, количество2: файл соответствует манифесту.

Для дедупликации важен контент; имя, метаданные и права доступа нужно учитывать отдельно. Строгое сравнение здесь относится к открытым отпечаткам. Если это секретный MAC, выбирайте hash_equals.

<?php
declare(strict_types=1);

$left = hash_file('sha256', __DIR__ . '/first.csv', true);
$right = hash_file('sha256', __DIR__ . '/second.csv', true);
if ($left === false || $right === false) { throw new RuntimeException('Read failed'); }

echo $left === $right ? "first.csv и second.csv содержат одинаковые байты.\n" : "Содержимое CSV различается.\n";

first.csv и second.csv содержат одинаковые байты.

Только учебная проверка намеренно перехватывает ожидаемое warning. В рабочем процессе отказ чтения останавливает проверку; предупреждения не скрывают глобально и пути/данные не выводят клиенту.

<?php
declare(strict_types=1);

$warnings = 0;
set_error_handler(function (int $level) use (&$warnings): bool {
    if ($level !== E_WARNING) { return false; }
    ++$warnings;
    return true;
});
try { $result = hash_file('sha256', __DIR__ . '/absent.txt'); }
finally { restore_error_handler(); }
echo $result === false && $warnings > 0 ? "Импорт остановлен: файл не прочитан, предупреждение получено.\n" : "Отказ не обнаружен.\n";

Импорт остановлен: файл не прочитан, предупреждение получено.

Ошибки и ограничения. Неверный algo и NUL в пути дают ValueError; невозможность чтения — warning/false. Интерфейс работает с wrappers, поэтому filename из запроса создаёт отдельный риск доступа к файлам/сети. В PHP 8.5 реализация читает блоками; файловый кэш ОС при этом может расти. Потоковое чтение не гарантирует неизменность файла между проверкой и использованием.

Продолжить: hash, hash_update_file, hash_update_stream, hash_hmac_file. Как выбрать задачу и алгоритм.

• PHP: hash_file

PHP 5.1.2+ · hash

hash_init(string $algo, int $flags = 0, string $key = "", array $options = []): HashContext

Получить отпечаток отчёта из двух строк. Создаёт пустое состояние вычисления. Переменная context хранит объект, который связывает следующие update и final. init сам не получает пользовательские байты.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Создать состояние вычисления, в которое данные будут поступать частями.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, "order=42\n");
hash_update($context, "qty=2\n");
$digest = hash_final($context);
echo 'Весь отчёт: ', $digest, "\n";
echo "Строки добавлены в порядке: order=42, затем qty=2.\n";

Весь отчёт: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987
Строки добавлены в порядке: order=42, затем qty=2.

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

<?php
declare(strict_types=1);

$key = 'demo-only-key';
$context = hash_init('sha256', HASH_HMAC, $key);
hash_update($context, 'order:');
hash_update($context, '42');
var_dump(hash_final($context) === hash_hmac('sha256', 'order:42', $key));
try { hash_init('sha256', HASH_HMAC, ''); }
catch (ValueError $error) { echo 'missing key rejected'; }

bool(true)
missing key rejected

Ошибки и ограничения. ValueError: неизвестный algo; некриптографический algo именно в HMAC-режиме; пустой ключ именно при HASH_HMAC. Обычный hash_init без ключа корректен. С 7.2 возвращается объект вместо resource; с 8.1 есть options; неверные типы некоторых options deprecated с 8.4. Отдельные правила xxHash смотрите в options.

Продолжить: hash_update, hash_final, hash_copy, hash_hmac. Как выбрать задачу и алгоритм.

• PHP: hash_init

PHP 5.1.2+ · hash

hash_update(HashContext $context, string $data): true

Получить отпечаток отчёта из двух строк. Добавляет следующую часть без разделителей. Поэтому LF пишем явно в строке. Результат update сообщает успех; окончательный digest возвращает отдельный final.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Добавить очередную строку байтов к активному вычислению.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, "order=42\n");
hash_update($context, "qty=2\n");
$digest = hash_final($context);
echo 'Весь отчёт: ', $digest, "\n";
echo "Строки добавлены в порядке: order=42, затем qty=2.\n";

Весь отчёт: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987
Строки добавлены в порядке: order=42, затем qty=2.

foreach берёт строки по порядку; здесь формат запрещает переводы строк внутри значения. Для произвольных полей нужен однозначный формат, например длина каждого поля перед его байтами. Hash не знает границы записей и не исправит неоднозначное склеивание.

<?php
declare(strict_types=1);

$records = ['order=42', 'qty=2'];
$context = hash_init('sha256');
foreach ($records as $record) {
    hash_update($context, $record . "\n");
}
$digest = hash_final($context);
echo "Проверены строки order=42 и qty=2 с LF.\nОтпечаток: ", $digest, "\n";

Проверены строки order=42 и qty=2 с LF.
Отпечаток: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987

Ошибки и ограничения. Неверный тип или уже финализированный context вызывает TypeError в PHP 8.5; true относится только к успешному вызову. С 7.2 параметр — HashContext. Порядок частей важен; хеш хешей отдельных блоков обычно не равен хешу исходного файла.

Продолжить: hash_init, hash_final, hash_update_file, hash_update_stream. Как выбрать задачу и алгоритм.

• PHP: hash_update

PHP 5.1.2+ · hash

hash_final(HashContext $context, bool $binary = false): string

Получить отпечаток отчёта из двух строк. Получает окончательную строку и завершает состояние. Сохраните результат в переменной: повторный final/update того же контекста недопустим.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Получить окончательный отпечаток и завершить конкретный контекст.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, "order=42\n");
hash_update($context, "qty=2\n");
$digest = hash_final($context);
echo 'Весь отчёт: ', $digest, "\n";
echo "Строки добавлены в порядке: order=42, затем qty=2.\n";

Весь отчёт: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987
Строки добавлены в порядке: order=42, затем qty=2.

Сохраняйте возвращённую строку, если она нужна ещё раз. Для промежуточного просмотра делают hash_final(hash_copy($context)); исходное вычисление при этом остаётся активным.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'report');
$saved = hash_final($context);
try { hash_final($context); }
catch (TypeError $error) { echo "Повторная финализация отклонена.\n"; }
echo "Ранее сохранённый отпечаток report: ", $saved, "\n";

Повторная финализация отклонена.
Ранее сохранённый отпечаток report: 845e91831319e89c4d656bdb80c278ac09a7230d61e5dfd2e1b1fbb436ac8917

Ошибки и ограничения. С 7.2 принимает объект. После final повторные hash_update/hash_final/hash_copy дают TypeError в текущем PHP, а прямой clone такого объекта — ValueError. Проверка instanceof HashContext не доказывает активность; состояние должно контролироваться вашим порядком вызовов.

Продолжить: hash_init, hash_copy, hash_update. Как выбрать задачу и алгоритм.

• PHP: hash_final

PHP 5.3+ · hash

hash_copy(HashContext $context): HashContext

Ответвить два отчёта от общего заголовка. copy создаёт независимое состояние. Обычное $second = $first сохранило бы ссылку на тот же объект. Здесь заголовок один, а количество у двух продолжений разное.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Ответвить независимое вычисление после общего префикса.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, "order=42\n");
$other = hash_copy($context);
hash_update($context, "qty=2\n");
hash_update($other, "qty=9\n");
echo 'Количество2: ', hash_final($context), "\n";
echo 'Количество9: ', hash_final($other), "\n";

Количество2: c061afdd8db7ecdf0b1ed01d735f3aebadc4d8f6e0d0cb42b6de4d41d3aad987
Количество9: 42ff9f4045168a6d0e5c6118703aa77232fface963bc464179e112d7e9894022

Обычное присваивание $second = $base указывало бы на тот же объект. Копия HMAC также содержит секретное рабочее состояние: не экспортируйте её и не считайте безопасным логом. Польза копирования зависит от длины общего префикса; для двух коротких строк отдельный hash_hmac проще.

<?php
declare(strict_types=1);

$key = 'demo-only-key';
$base = hash_init('sha256', HASH_HMAC, $key);
hash_update($base, 'shop:v1:');
$first = hash_copy($base);
$second = hash_copy($base);
hash_update($first, 'order:42');
hash_update($second, 'order:43');
var_dump(hash_final($first) === hash_hmac('sha256', 'shop:v1:order:42', $key));
var_dump(hash_final($second) === hash_hmac('sha256', 'shop:v1:order:43', $key));

bool(true)
bool(true)

Ошибки и ограничения. Доступно с 5.3, с 7.2 работает с HashContext. Невалидный/финализированный context даёт TypeError; невозможность внутреннего копирования — Error. Native clone активного HashContext тоже копирует состояние, но явный hash_copy легче узнаётся в потоковом коде.

Продолжить: hash_final, hash_init, HashContext::__serialize. Как выбрать задачу и алгоритм.

• PHP: hash_copy

PHP 5.1.2+ · hash

hash_update_stream(HashContext $context, resource $stream, int $length = -1): int

Прочитать ровно полезную часть пакета. packet.txt содержит HEADabcTAIL. fopen с rb открывает байты без преобразования строк, fseek4 пропускает четыре байта заголовка, length3 ограничивает чтение содержимым abc.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Добавить байты из уже открытого потока, начиная с его текущей позиции.

<?php
declare(strict_types=1);

$stream = fopen(__DIR__ . '/packet.txt', 'rb');
if ($stream === false) { throw new RuntimeException('Пакет недоступен'); }
try {
    if (fseek($stream, 4) !== 0) { throw new RuntimeException('Не удалось пропустить HEAD'); }
    $context = hash_init('sha256');
    if (hash_update_stream($context, $stream, 3) !== 3) { throw new RuntimeException('Пакет обрезан'); }
    echo 'Поле abc: ', hash_final($context), "\n";
    echo 'Остаток потока: ', stream_get_contents($stream), "\n";
} finally { fclose($stream); }

Поле abc: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
Остаток потока: TAIL

Контракт ожидал ровно пять байтов; три уже изменили context, поэтому ошибку нельзя исправить простым повтором всего файла в тот же контекст. Начинают новый расчёт после решения причины сбоя. Для чтения до EOF проверка зависит от известного размера и типа потока.

<?php
declare(strict_types=1);

$stream = fopen(__DIR__ . '/short.txt', 'rb');
if ($stream === false) { throw new RuntimeException('Open failed'); }
try {
    $context = hash_init('sha256');
    $added = hash_update_stream($context, $stream, 5);
    echo $added, "\n";
    if ($added !== 5) { echo 'incomplete: discard context'; }
    else { echo hash_final($context); }
} finally { fclose($stream); }

3
incomplete: discard context

Ошибки и ограничения. Неверный/закрытый stream resource и завершённый context приводят к TypeError. Ошибка чтения может дать warning и короткое число вместо исключения; возврат не равен гарантии целостности источника. С 7.2 context — объект. Для локальных бинарных файлов открывайте rb: текстовый режим может изменять байты на отдельных платформах.

Продолжить: hash_update_file, hash_file, hash_final. Как выбрать задачу и алгоритм.

• PHP: hash_update_stream

PHP 5.1.2+ · hash

hash_update_file(HashContext $context, string $filename, ?resource $stream_context = null): bool

Добавить файл после версии формата. Первый аргумент — уже открытый HashContext, второй — имя файла. Это другой объект, чем stream_context с настройками чтения. Возвращаемый bool необходимо проверить до final.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Добавить весь файл к уже накопленному префиксу вычисления.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, "format:v1\n");
if (!hash_update_file($context, __DIR__ . '/export.txt')) { throw new RuntimeException('Отчёт не прочитан; результат не выдаём'); }
echo 'Версия и файл: ', hash_final($context), "\n";

Версия и файл: 075dcceb6e9f5aedd33f9fff27a41605f9e9021e53cf5db7b5835e3437d5c25c

Не финализируем только заголовок и не выдаём его за сумму полного документа. При частичном сбое нет автоматического rollback: новый повтор — новый контекст. Обработчик warning временный и нужен только для детерминированной демонстрации.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'format-v1:');
$warnings = 0;
set_error_handler(function (int $level) use (&$warnings): bool {
    if ($level !== E_WARNING) { return false; }
    ++$warnings; return true;
});
try { $ok = hash_update_file($context, __DIR__ . '/missing.txt'); }
finally { restore_error_handler(); }
if (!$ok) { unset($context); echo 'discarded', "\n"; }
var_dump($warnings > 0);

discarded
bool(true)

Ошибки и ограничения. Отказ I/O — warning/false; неверный context или stream_context — TypeError; NUL в filename — ValueError. Поддержка wrappers не разрешает принимать произвольный пользовательский URL. Если нужен один файл без префикса, hash_file короче и понятнее.

Продолжить: hash_file, hash_update_stream, hash_update, hash_final. Как выбрать задачу и алгоритм.

• PHP: hash_update_file

PHP 7.2+ · hash

hash_hmac_algos(): array

Проверить алгоритм перед проверкой экспорта. Список hash_hmac_algos содержит алгоритмы, допустимые именно для HMAC. Наличие имени не означает, что его разрешила политика сервиса. Выбираем sha256 явно и отказываем при отсутствии.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Получить список алгоритмов, для которых PHP реализует HMAC.

<?php
declare(strict_types=1);

if (!in_array('sha256', hash_hmac_algos(), true)) { throw new RuntimeException('Нет обязательного sha256'); }
echo "Проверка экспорта: sha256 доступен.\n";
echo 'Контрольный результат: ', hash_hmac('sha256', 'order=42', 'local-demo-key'), "\n";

Проверка экспорта: sha256 доступен.
Контрольный результат: 656a184e13c773994fcbc3e7a6030a261700ca9545352c0fb7142f52352e2e1b

Проверка происходит при настройке сервиса. Не переключаемся с неизвестного алгоритма на MD5 для «совместимости» и не берём алгоритм из незащищённого заголовка без протокольного правила.

<?php
declare(strict_types=1);

$configured = 'sha256';
$policy = ['sha256', 'sha512'];
if (!in_array($configured, $policy, true)
    || !in_array($configured, hash_hmac_algos(), true)) {
    throw new RuntimeException('Unsupported configured MAC');
}
echo 'MAC configuration accepted';

MAC configuration accepted

Ошибки и ограничения. Функция появилась в 7.2; раньше отдельного списка не было. Порядок и полный набор могут меняться между версиями. То, что MD5/SHA-1 исторически присутствует, не делает их разумным выбором нового протокола.

Продолжить: hash_algos, hash_hmac, hash_hkdf. Как выбрать задачу и алгоритм.

• PHP: hash_hmac_algos

PHP 5.1.2+ · hash

hash_hmac_file(string $algo, string $filename, string $key, bool $binary = false): string|false

Принять подлинную учебную запись и отклонить изменение. HMAC вычисляет проверочную строку из точных байтов и отдельного общего ключа. Ключ — третий аргумент; дописать его к тексту и вызвать hash означало бы другую конструкцию. В опыте отправитель и получатель локальные, ключ намеренно учебный; вывод MAC здесь воспроизводим, реальный ключ не публикуют.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Вычислить MAC содержимого файла с известным обеим сторонам ключом.

<?php
declare(strict_types=1);

$known = hash_hmac_file('sha256', __DIR__ . '/export.txt', 'local-demo-key');
if ($known === false) { throw new RuntimeException('Файл не прочитан'); }
$received = $known;
echo 'Подпись: ', $known, "\n";
echo hash_equals($known, $received) ? "Исходная запись принята.\n" : "Подпись не совпала.\n";
$changed = hash_hmac('sha256', 'order=43', 'local-demo-key');
echo hash_equals($known, $changed) ? "Изменение принято.\n" : "Изменённая запись отклонена.\n";

Подпись: d9bcbf1b3f2fdb7cf18f3a4ca777e268b1a101282c62de32d548acd5d1c43444
Исходная запись принята.
Изменённая запись отклонена.

Подписано количество 2, а fixture содержит 3. Реальный ожидаемый MAC принимают в определённом формате и проверяют его тип/длину; файл фиксируют от изменения до использования. HMAC не запрещает повторно импортировать тот же корректный файл.

<?php
declare(strict_types=1);

$key = 'demo-only-key';
$expected = hash_hmac('sha256', "id,qty\n42,2\n", $key, true);
$actual = hash_hmac_file('sha256', __DIR__ . '/changed.csv', $key, true);
if ($actual === false) { throw new RuntimeException('Read failed'); }
echo hash_equals($expected, $actual) ? 'import allowed' : 'reject before import';

reject before import

Ошибки и ограничения. Неизвестный/некриптографический algo — ValueError (современный контракт с 8.0); некриптографические HMAC запрещены с 7.2. Отказ I/O — warning/false; NUL в пути — ValueError. Не принимайте произвольные wrappers из запроса. Дополнительных algorithm options/stream_context в этой сигнатуре нет.

Продолжить: hash_hmac, hash_equals, hash_update_file, hash_init. Как выбрать задачу и алгоритм.

• PHP: hash_hmac_file

PHP 7.1.2+ · hash

hash_hkdf(string $algo, string $key, int $length = 0, string $info = "", string $salt = ""): string

Разделить ключи двух назначений. HKDF получает уже стойкий исходный ключ, длину результата в байтах, строку назначения info и salt. Это не медленная проверка человеческого пароля. Разные info отделяют подпись выгрузки от уведомления.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Получить отдельный ключ для конкретной роли из исходного ключевого материала.

<?php
declare(strict_types=1);

$master = str_repeat('M', 32); // Only a reproducible local fixture.
$exportKey = hash_hkdf('sha256', $master, 32, 'shop/export/v1', 'demo-salt');
$notifyKey = hash_hkdf('sha256', $master, 32, 'shop/notify/v1', 'demo-salt');
$signature = hash_hmac('sha256', 'order=42', $exportKey);
echo hash_equals($signature, hash_hmac('sha256', 'order=42', $exportKey)) ? "Экспорт: подпись принята.\n" : "Экспорт: отказ.\n";
echo hash_equals($signature, hash_hmac('sha256', 'order=42', $notifyKey)) ? "Уведомление: подпись принята.\n" : "Уведомление: чужое назначение отклонено.\n";

Экспорт: подпись принята.
Уведомление: чужое назначение отклонено.

Общее корневое значение не означает один ключ на все роли. Случайная соль от random_bytes должна сохраняться/передаваться по протоколу; генерация новой соли при каждой проверке изменила бы результат. Фиксированные разные info поддерживают разделение назначений; компрометация master компрометирует производные ключи.

<?php
declare(strict_types=1);

$master = str_repeat('M', 32);
$salt = 'demo-salt';
$exportKey = hash_hkdf('sha256', $master, 32, 'shop/export/v1', $salt);
$notifyKey = hash_hkdf('sha256', $master, 32, 'shop/notify/v1', $salt);
echo $exportKey !== $notifyKey ? "Ключи экспорта и уведомления разделены.\n" : "Назначения получили один ключ.\n";
$exportMac = hash_hmac('sha256', 'id=42', $exportKey);
$notifyMac = hash_hmac('sha256', 'id=42', $notifyKey);
echo hash_equals($exportMac, $notifyMac) ? "Подпись другого назначения принята.\n" : "Подпись другого назначения отклонена.\n";

Ключи экспорта и уведомления разделены.
Подпись другого назначения отклонена.

Размер ограничивается digest_size×255, а не длиной текстового hex. Ключ/вывод не печатаем в рабочей диагностике: достаточно категории отказа.

<?php
declare(strict_types=1);

foreach ([['', 32], ['demo', -1], ['demo', 8161]] as [$key, $length]) {
    try { hash_hkdf('sha256', $key, $length); }
    catch (ValueError $error) { echo 'rejected', "\n"; }
}

rejected
rejected
rejected

Ошибки и ограничения. Появилась в 7.1.2. С 8.0 ValueError при пустом key, неизвестном/некриптографическом algo, отрицательном или слишком большом length; раньше warning/false. HKDF концентрирует имеющуюся энтропию, не создаёт её из предсказуемого секрета. Не заменяет протокольный обмен ключами.

Продолжить: hash_pbkdf2, hash_hmac, hash_hmac_algos. Как выбрать задачу и алгоритм.

• PHP: hash_hkdf

PHP 5.5+ · hash

hash_pbkdf2(string $algo, string $password, string $salt, int $iterations, int $length = 0, bool $binary = false, array $options = []): string

Восстановить ключ известного старого формата. Это низкоуровневое получение ключа из фразы: алгоритм, пароль, соль, итерации, длина, binary. При true длина означает байты; при false — hex-знаки. Для новых аккаунтов PHP предоставляет password_hash.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Воспроизвести согласованное PBKDF2-выведение ключа из пароля.

<?php
declare(strict_types=1);

$key = hash_pbkdf2('sha256', 'password', 'salt', 2, 16, true);
echo 'Тестовый ключ в hex: ', bin2hex($key), "\n";
$expected = hex2bin('ae4d0c95af6b46d32d0adff928f06dd0');
echo hash_equals($expected, $key) ? "Формат восстановлен; совместимость подтверждена.\n" : "Формат несовместим.\n";

Тестовый ключ в hex: ae4d0c95af6b46d32d0adff928f06dd0
Формат восстановлен; совместимость подтверждена.

Метаданные здесь заданы программой; недоверенный файл нельзя бесконтрольно пускать в derivation. До вызова проверяют допустимый алгоритм, диапазон iterations/length, длину соли и общий бюджет работы. Иначе запрос может занять CPU/память. Не сохраняйте секретную фразу вместе с этими параметрами.

<?php
declare(strict_types=1);

$format = ['algo' => 'sha256', 'iterations' => 2,
    'length' => 16, 'salt_hex' => bin2hex('fixture-salt')];
$salt = hex2bin($format['salt_hex']);
if ($salt === false) { throw new RuntimeException('Bad fixture salt'); }
$key = hash_pbkdf2($format['algo'], 'demo phrase', $salt,
    $format['iterations'], $format['length'], true);
$again = hash_pbkdf2($format['algo'], 'demo phrase', $salt,
    $format['iterations'], $format['length'], true);
echo "Метаданные формата: sha256,2раунда,16байтов, соль fixture-salt.\n";
echo hash_equals($key, $again) ? "По тем же метаданным восстановлен тот же ключ.\n" : "Ключи различаются.\n";

Метаданные формата: sha256,2раунда,16байтов, соль fixture-salt.
По тем же метаданным восстановлен тот же ключ.

Положительность — только минимальное условие PHP, не проверка достаточной стойкости. Стоимость растёт с iterations и количеством выходных блоков; измерение и ограничение частоты входа остаются задачей приложения.

<?php
declare(strict_types=1);

foreach ([[0, 16], [2, -1]] as [$rounds, $length]) {
    try { hash_pbkdf2('sha256', 'demo', 'salt', $rounds, $length, true); }
    catch (ValueError $error) { echo 'rejected', "\n"; }
}

rejected
rejected

Ошибки и ограничения. Функция с 5.5; запрет некриптографических алгоритмов с 7.2; с 8.0 ошибки дают ValueError: неподдерживаемый algo, iterations≤0, length<0, соль длиннее INT_MAX−4. Последнее — предел C int, не PHP_INT_MAX на 64-bit; огромную соль нельзя выделять ради теста. options добавлен в 8.3 (сверено по PHP stub 8.2/8.3); для базы PHP 8.2 достаточно первых шести аргументов. Неизвестные типы password/salt и других аргументов при strict_types=1 дают TypeError.

Продолжить: hash_hkdf, hash_hmac_algos, hash_equals. Как выбрать задачу и алгоритм.

• PHP: hash_pbkdf2

PHP 7.2+ · hash

private HashContext::__construct()

Управлять состоянием вычисления заказа. Конструктор private: new HashContext недоступен. Рабочий объект создаёт фабрика hash_init, которая выбирает алгоритм и инициализирует состояние.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Понять, почему контекст создают hash_init, а не через new.

<?php
declare(strict_types=1);

try { new HashContext(); } catch (Error) { echo "Прямое создание закрыто; используем hash_init.\n"; }
$context = hash_init('sha256');
hash_update($context, 'order=42');
echo 'Отчёт: ', hash_final($context), "\n";

Прямое создание закрыто; используем hash_init.
Отчёт: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705

Фабрика — обычная функция, которая возвращает подготовленный объект. Здесь два вызова дают два разных состояния. У HashContext нельзя сделать подкласс: класс final, его собственную реализацию расширяют композицией, если это действительно нужно.

<?php
declare(strict_types=1);

$first = hash_init('sha256');
$second = hash_init('sha256');
hash_update($first, 'first');
hash_update($second, 'second');
echo $first !== $second ? "Созданы независимые состояния двух документов.\n" : "Использовано одно состояние.\n";
echo "Документ first: ", hash_final($first), "\n";
echo "Документ second: ", hash_final($second), "\n";

Созданы независимые состояния двух документов.
Документ first: a7937b64b8caa58f03721bb6bacf5c78cb235febe0e70b1b84cd99541461a08e
Документ second: 16367aacb67a4a017c8da8ab95682ccb390863780f7114dda0a0e0c55644c7c4

Ошибки и ограничения. HashContext появился в PHP 7.2 вместо resource. Прямой вызов private-конструктора даёт Error. Нельзя обойти жизненный цикл ради пустого контейнера и затем работать с ним как с корректным хешем.

Продолжить: hash_init, hash_copy. Как выбрать задачу и алгоритм.

• PHP: HashContext::__construct

PHP 8.4+ · hash

HashContext::__debugInfo(): array

Управлять состоянием вычисления заказа. В PHP8.4+ диагностический метод возвращает поле algo. Стрелка вызывает метод именно этого объекта. Диагностика не завершает вычисление и не даёт хеш исходных данных.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Увидеть алгоритм контекста в диагностическом выводе.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'order=');
$info = $context->__debugInfo();
echo 'Выбран алгоритм: ', $info['algo'], "\n";
hash_update($context, '42');
echo 'Отчёт: ', hash_final($context), "\n";

Выбран алгоритм: sha256
Отчёт: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705

Прямой вызов сделан только для изучения возвращаемого массива hook. В прикладном коде алгоритм хранится в собственной конфигурации; не строят протокол на debug-выводе. Стрелка -> вызывает метод конкретного объекта; результат — обычный массив.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'a');
$info = $context->__debugInfo();
echo $info['algo'], "\n";
hash_update($context, 'bc');
echo "После диагностики продолжен abc: ", hash_final($context), "\n";

sha256
После диагностики продолжен abc: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Ошибки и ограничения. Метод добавлен в 8.4: на 8.2/8.3 этого API нет. Не использовать debug-массив для проверки, завершён ли context: он не обещает такого поля. Не выводить ключи/сырые сообщения вручную рядом с безопасным полем algo.

Продолжить: hash_init, hash_final. Как выбрать задачу и алгоритм.

• PHP: HashContext::__debugInfo

PHP 8.0+ · hash

HashContext::__serialize(): array

Управлять состоянием вычисления заказа. serialize вызывает __serialize и получает поддерживаемое состояние незавершённого расчёта. Снимок в примере создаётся самим PHP из собственных байтов в том же процессе. HMAC-состояние экспортировать нельзя.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Сохранить поддерживаемое активное состояние обычного хеширования.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'order=');
$ownSnapshot = serialize($context);
$restored = unserialize($ownSnapshot, ['allowed_classes' => [HashContext::class]]);
if (!$restored instanceof HashContext) { throw new RuntimeException('Не восстановлен собственный снимок'); }
hash_update($restored, '42');
echo 'Продолженный отчёт: ', hash_final($restored), "\n";
hash_update($context, '43');
echo 'Независимый оригинал: ', hash_final($context), "\n";

Продолженный отчёт: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705
Независимый оригинал: 96df9bbc8108b8389a59245f6814791cb08630fe0d63cacd70fe5127ee635ea0

HMAC запрещён, чтобы не экспортировать секретное состояние. Финализация уже освободила рабочий буфер. Вместо сохранения результата вычисления храните сам возвращённый digest; для разветвления активного процесса используйте hash_copy.

<?php
declare(strict_types=1);

$hmac = hash_init('sha256', HASH_HMAC, 'demo-only-key');
try { serialize($hmac); }
catch (Exception $error) { echo 'HMAC not serializable', "\n"; }
$finished = hash_init('sha256');
hash_final($finished);
try { serialize($finished); }
catch (Exception $error) { echo 'finished state rejected'; }

HMAC not serializable
finished state rejected

Ошибки и ограничения. Метод существует с 8.0. В PHP 8.5 сериализация HMAC, завершённого состояния SHA-256 или неподдерживаемого алгоритмом формата вызывает Exception. Внутренний массив включает алгоритм, режим, состояние, версию представления и свойства; схему не следует собирать вручную. Состояние может содержать буфер последних байтов исходного сообщения: не логируйте его и не передавайте клиенту.

Продолжить: HashContext::__unserialize, hash_copy, hash_final. Как выбрать задачу и алгоритм.

• PHP: HashContext::__serialize

PHP 8.0+ · hash

HashContext::__unserialize(array $data): void

Управлять состоянием вычисления заказа. unserialize создаёт восстановленный объект и вызывает его __unserialize. allowed_classes ограничивает тип, но не делает чужие данные безопасными. Снимок в примере создаётся самим PHP из собственных байтов в том же процессе. HMAC-состояние экспортировать нельзя.

Распакуйте все файлы архива вместе. Команда php example.php выполняет этот пример; файлы из архива не нужно придумывать самостоятельно.

Восстановить собственный доверенный снимок HashContext для продолжения вычисления.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'order=');
$ownSnapshot = serialize($context);
$restored = unserialize($ownSnapshot, ['allowed_classes' => [HashContext::class]]);
if (!$restored instanceof HashContext) { throw new RuntimeException('Не восстановлен собственный снимок'); }
hash_update($restored, '42');
echo 'Продолженный отчёт: ', hash_final($restored), "\n";
hash_update($context, '43');
echo 'Независимый оригинал: ', hash_final($context), "\n";

Продолженный отчёт: e7be97a0dece7cd8751b91338ce03d916b01ee32616d2b8b70e1807e5f307705
Независимый оригинал: 96df9bbc8108b8389a59245f6814791cb08630fe0d63cacd70fe5127ee635ea0

Учебный прямой вызов демонстрирует запрет: active object нельзя переинициализировать таким способом. Нормальный маршрут — unserialize доверенного снимка в другой объект. Не строим ручной обход private-конструктора через Reflection.

<?php
declare(strict_types=1);

$context = hash_init('sha256');
hash_update($context, 'ab');
$state = $context->__serialize();
try { $context->__unserialize($state); }
catch (Exception $error) { echo 'already initialized', "\n"; }
hash_update($context, 'c');
echo "Исходный контекст продолжил abc: ", hash_final($context), "\n";

already initialized
Исходный контекст продолжил abc: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Ошибки и ограничения. С 8.0. Неверный тип data даёт TypeError; уже активный объект, повреждённая/неполная схема, неизвестный алгоритм, HMAC-режим или непригодное внутреннее состояние — Exception в текущей реализации. Не подавляйте эти ошибки и не принимайте snapshots извне. Формат не гарантированно переносим между PHP/архитектурами.

Продолжить: HashContext::__serialize, hash_init, hash_copy. Как выбрать задачу и алгоритм.

• PHP: HashContext::__unserialize