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

Первый результат: чек внутри TAR

Нужно передать несколько документов одним файлом. Начнём с архива данных TAR: он хранит имена и байты, но не запускает программу. PharData позволяет создать такой контейнер и прочитать чек без установки отдельного архиватора.

$archive = new PharData(...) создаёт объект для выбранного файла; __DIR__ означает папку PHP-скрипта. Запись $archive["receipt.txt"] = ... кладёт строку под именем внутри контейнера. Чтение тех же квадратных скобок даёт объект записи, а ->getContent() возвращает текст. echo выводит его; \n переводит строку.

<?php
declare(strict_types=1);

$archive = new PharData(__DIR__ . '/receipt.tar');
$archive['receipt.txt'] = "Заказ 42: готов к выдаче\n";
echo $archive['receipt.txt']->getContent();

Заказ 42: готов к выдаче

Аналогия с папкой объясняет имена, но архив не является обычной папкой ОС: изменение может потребовать перезаписать контейнер; права/форматы/сжатие имеют отдельные ограничения. require чужого .phar выполняет чужой код. Для импорта документов выбирайте данные и проверяйте их как данные.

Полные исходники карточек и команда запуска

Каждый архив карточки самостоятельный: example.php, bootstrap.php и два UTF-8 файла input. Все пути задаёт программа. Распакуйте в новую папку, затем выполните php -d phar.readonly=0 example.php. Флаг нужен только отдельному процессу сборки исполняемого Phar; общий php.ini не меняется. Для обычного PharData запись данных работает и с phar.readonly=1 — это проверяется проектом ниже.

Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

Получить заказ в пункте № 3.

В bootstrap.php foreach перебирает два имени. addFile получает путь источника и имя внутри контейнера. Исключение прерывает ошибочный путь; исходники не удаляются. Для PharData тот же шаблон использует new PharData и orders.zip; отдельные карточки сжатия целого контейнера используют orders.tar.

<?php
$path = __DIR__ . '/orders.phar';
if (file_exists($path)) { throw new RuntimeException('Запускайте пример в новой папке'); }
$archive = new Phar($path);
foreach (['receipt.txt', 'notice.txt'] as $name) {
    $archive->addFile(__DIR__ . '/input/' . $name, $name);
}

Полный обмен документами: TAR.GZ и безопасное чтение

Отправитель приложил два документа; получатель должен получить received/receipt.txt и received/notice.txt. Создаём настоящий orders.tar, сжимаем в orders.tar.gz, читаем архив напрямую через PharData и сохраняем только два разрешённых файла. Весь пример запускается с php -d phar.readonly=1 example.php: обычные данные разрешено создавать и при защите исполняемых Phar.

import.php определяет receiveDocuments(path, destination): void. Проверки идут до создания папки: вход до32КиБ, ровно две записи, точные имена, обычные файлы без ссылок, каждый до1024байт. Чтение 1025байт обнаруживает превышение. rb читает байты, xb создаёт новый файл с отказом при существующем имени; finally закрывает поток при любом исходе. foreach пишет только константные имена. При ошибке записи catch удаляет только файлы, которые создал этот вызов в своей новой папке.

<?php
function receiveDocuments(string $path, string $destination): void {
    if (!is_file($path)) { throw new RuntimeException('Нет файла поставки'); }
    $bytes = filesize($path);
    if ($bytes === false || $bytes > 32768) { throw new RuntimeException('Слишком большой вход'); }
    if (file_exists($destination)) { throw new RuntimeException('Папка результата уже существует'); }
    $archive = new PharData($path);
    if ($archive->count() !== 2) { throw new RuntimeException('Нужны ровно два документа'); }
    $documents = [];
    foreach (['receipt.txt', 'notice.txt'] as $name) {
        if (!isset($archive[$name])) { throw new RuntimeException('Неожиданный состав архива'); }
        $entry = $archive[$name];
        if (!$entry->isFile() || $entry->isLink() || $entry->getSize() > 1024) {
            throw new RuntimeException('Нужен небольшой обычный файл');
        }
        $stream = fopen($entry->getPathname(), 'rb');
        if ($stream === false) { throw new RuntimeException('Документ не открывается'); }
        try { $text = stream_get_contents($stream, 1025); }
        finally { fclose($stream); }
        if ($text === false || strlen($text) > 1024 || strlen($text) !== $entry->getSize()) {
            throw new RuntimeException('Документ повреждён или превышает лимит');
        }
        $documents[$name] = $text;
    }
    if (!mkdir($destination, 0700)) { throw new RuntimeException('Не создана папка результата'); }
    $created = [];
    try {
        foreach (['receipt.txt', 'notice.txt'] as $name) {
            $target = $destination . '/' . $name;
            $stream = fopen($target, 'xb');
            if ($stream === false) { throw new RuntimeException('Не создан файл'); }
            $created[] = $target;
            try {
                if (fwrite($stream, $documents[$name]) !== strlen($documents[$name])) {
                    throw new RuntimeException('Не завершена запись');
                }
            } finally { fclose($stream); }
        }
    } catch (Throwable $error) {
        foreach ($created as $target) { unlink($target); }
        rmdir($destination);
        throw $error;
    }
}

Ниже example.php: создаёт входы, вызывает receiveDocuments и печатает реальные сохранённые файлы. Следующий foreach проверяет четыре заданных отказа; catch выбирает сообщение человеку. Полный import.php и input вложены в ZIP. Уже существующая received защищена от повторной поставки.

<?php
declare(strict_types=1);

require __DIR__ . '/import.php';
$archive = new PharData(__DIR__ . '/orders.tar');
foreach (['receipt.txt', 'notice.txt'] as $name) {
    $archive->addFile(__DIR__ . '/input/' . $name, $name);
}
$packed = $archive->compress(Phar::GZ);
if ($packed === null) { throw new RuntimeException('Нет orders.tar.gz'); }
receiveDocuments($packed->getPath(), __DIR__ . '/received');
echo "received/receipt.txt:\n", file_get_contents(__DIR__ . '/received/receipt.txt');
echo "received/notice.txt:\n", file_get_contents(__DIR__ . '/received/notice.txt');
$wrong = new PharData(__DIR__ . '/wrong.tar');
$wrong['other.txt'] = 'Неожиданный документ';
$wrong['notice.txt'] = 'Памятка';
$large = new PharData(__DIR__ . '/large.tar');
$large['receipt.txt'] = str_repeat('x', 1025);
$large['notice.txt'] = 'Памятка';
file_put_contents(__DIR__ . '/broken.tar', 'Это текст, а не TAR');
foreach (['wrong.tar', 'large.tar', 'broken.tar', 'missing.tar'] as $name) {
    try { receiveDocuments(__DIR__ . '/' . $name, __DIR__ . '/rejected'); }
    catch (UnexpectedValueException $error) { echo $name, ": Не удалось открыть исправный TAR/ZIP\n"; }
    catch (RuntimeException $error) { echo $name, ': ', $error->getMessage(), "\n"; }
    if (file_exists(__DIR__ . '/rejected')) { throw new RuntimeException('Отказ оставил результат'); }
}
try { receiveDocuments($packed->getPath(), __DIR__ . '/received'); }
catch (RuntimeException $error) { echo 'Повторная поставка: ', $error->getMessage(), "\n"; }
echo "Сохранённый чек не изменился:\n", file_get_contents(__DIR__ . '/received/receipt.txt');

received/receipt.txt:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.
received/notice.txt:
Получить заказ в пункте № 3.
wrong.tar: Неожиданный состав архива
large.tar: Нужен небольшой обычный файл
broken.tar: Не удалось открыть исправный TAR/ZIP
missing.tar: Нет файла поставки
Повторная поставка: Папка результата уже существует
Сохранённый чек не изменился:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

Полное приложение: сборка, stub и фактический запуск

Теперь другая задача: выдать собственную PHP-программу как один app.phar. Файлы source/main.php и source/stub.php находятся в архиве примера; сборщик помещает main.php и receipt.txt внутрь app.phar и устанавливает stub. После сборки для запуска достаточно php app.phar. Ни один внешний сервис не вызывается.

main.php читает receipt.txt относительно своей внутренней папки и выводит чек. Stub сначала вызывает mapPhar, затем require внутреннего main.php. __HALT_COMPILER(); обязательно завершает PHP-часть: после неё начинается бинарный контейнер. В stub __FILE__ — внешнее имя app.phar, а в main.php __DIR__ — внутренняя phar:// папка.

source/main.php

<?php
$text = file_get_contents(__DIR__ . '/receipt.txt');
if ($text === false) { throw new RuntimeException('Нет чека в приложении'); }
echo $text;

source/stub.php

<?php
Phar::mapPhar();
require 'phar://' . __FILE__ . '/main.php';
__HALT_COMPILER();

<?php
declare(strict_types=1);

$path = __DIR__ . '/app.phar';
if (file_exists($path)) { throw new RuntimeException('Нужна новая папка для сборки'); }
$archive = new Phar($path);
$archive->addFile(__DIR__ . '/input/receipt.txt', 'receipt.txt');
$archive->addFile(__DIR__ . '/source/main.php', 'main.php');
$stub = file_get_contents(__DIR__ . '/source/stub.php');
if ($stub === false) { throw new RuntimeException('Нет загрузчика'); }
$archive->setStub($stub);
$archive->setSignatureAlgorithm(Phar::SHA256);
echo "app.phar собран; запуск собственного приложения:\n";
require $path;

app.phar собран; запуск собственного приложения:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

При повреждённом архиве конструктор/загрузчик должен отказать, а не продолжать работу. При неверном стартовом имени standard stub не найдёт main.php. На следующей ступени webPhar выдаёт PHP-страницу и статический текст по localhost, а mount показывает внешнюю настройку, не упакованную в приложение.

Следующие ситуации: потоки, дерево файлов, защита и повреждение

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

Открытый поток можно передать offsetSet: fopen(..., "rb") создаёт дескриптор чтения, try/finally гарантирует fclose после копирования. Так не нужно сначала получать весь большой источник через file_get_contents в одну строку.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
$stream = fopen(__DIR__ . '/input/receipt.txt', 'rb');
if ($stream === false) { throw new RuntimeException('Нет исходника'); }
try { $archive->offsetSet('stream-copy.txt', $stream); }
finally { fclose($stream); }
echo $archive['stream-copy.txt']->getContent();

Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

DirectoryIterator возвращает SplFileInfo для элементов папки. RecursiveDirectoryIterator и RecursiveIteratorIterator обходят вложенные элементы; SKIP_DOTS пропускает . и ... Для такой формы buildFromIterator второй аргумент baseDirectory обязателен: он определяет, какую часть внешнего пути убрать из имени записи.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
$base = __DIR__ . '/input';
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($base, FilesystemIterator::SKIP_DOTS));
$mapping = $archive->buildFromIterator($iterator, $base);
ksort($mapping);
foreach ($mapping as $inside => $disk) { echo $inside, ":\n", $archive[$inside]->getContent(); }

notice.txt:
Получить заказ в пункте № 3.
receipt.txt:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

Контекст — массив настроек конкретной потоковой операции. Здесь секция phar задаёт compress и metadata; четвёртый аргумент file_put_contents передаёт контекст, третий 0 оставляет обычные флаги записи. Не добавляйте FILE_APPEND: обёртка Phar не поддерживает дописывание.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
$context = stream_context_create(['phar' => ['compress' => Phar::GZ, 'metadata' => ['title' => 'Квитанция']]]);
$text = "Заказ 42: выдан\n";
$url = 'phar://' . $path . '/delivery.txt';
if (file_put_contents($url, $text, 0, $context) !== strlen($text)) { throw new RuntimeException('Не записана квитанция'); }
$entry = $archive['delivery.txt'];
$metadata = $entry->getMetadata(['allowed_classes' => false]);
echo $metadata['title'], ":\n", $entry->getContent();

Квитанция:
Заказ 42: выдан

Защиту записи можно включить внутри процесса, если при запуске разрешили сборку. После ini_set("phar.readonly", "1") попытка изменить исполняемый архив должна завершиться исключением. Обычный PharData продолжает работать с данными.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
ini_set('phar.readonly', '1');
try { $archive['receipt.txt'] = 'Нежелательная замена'; }
catch (BadMethodCallException $error) { echo "Изменение исполняемого пакета запрещено\n"; }
echo $archive['receipt.txt']->getContent();
$data = new PharData(__DIR__ . '/delivery.tar');
$data['delivery.txt'] = "Данные выдачи записаны отдельно\n";
echo $data['delivery.txt']->getContent();

Изменение исполняемого пакета запрещено
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.
Данные выдачи записаны отдельно

Повреждённый контейнер, неверный загрузчик и отсутствующий исходный файл — три разные причины отказа. В демонстрации catch Exception собирает понятный текст для человека, а точную техническую причину сохраняет в diagnostic.txt внутри своей папки.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
$diagnostics = [];
file_put_contents(__DIR__ . '/broken.phar', 'Повреждённая поставка');
try { new Phar(__DIR__ . '/broken.phar'); }
catch (Exception $error) { $diagnostics[] = $error->getMessage(); echo "Повреждённый контейнер отклонён\n"; }
try { $archive->setStub('<?php echo 42;'); }
catch (Exception $error) { $diagnostics[] = $error->getMessage(); echo "Загрузчик без __HALT_COMPILER отклонён\n"; }
try { $archive->addFile(__DIR__ . '/missing.txt', 'missing.txt'); }
catch (Exception $error) { $diagnostics[] = $error->getMessage(); echo "Отсутствующий исходник отклонён\n"; }
file_put_contents(__DIR__ . '/diagnostic.txt', implode("\n", $diagnostics));
echo "Исходный чек доступен:\n";
echo $archive['receipt.txt']->getContent();

Повреждённый контейнер отклонён
Загрузчик без __HALT_COMPILER отклонён
Отсутствующий исходник отклонён
Исходный чек доступен:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

Bzip2 — отдельная зависимость. В следующем опыте явно требуется bz2; если расширения нет, пример не следует объявлять выполненным. Способ сжатия контейнера не меняет текст документов.

<?php
declare(strict_types=1);

require __DIR__ . '/bootstrap.php';
if (!Phar::canCompress(Phar::BZ2)) { throw new RuntimeException('Нужно расширение bz2'); }
$packed = $archive->compress(Phar::BZ2);
if ($packed === null) { throw new RuntimeException('Нет сжатой поставки'); }
echo $packed['receipt.txt']->getContent();

Заказ 42
Кисть — 2 шт.
Итого: 300 руб.

Настоящая подпись: свежий процесс и правильный открытый ключ

Хеш SHA256 может пересчитать любой изменивший архив. Асимметричная подпись использует закрытый ключ издателя; получатель проверяет её доверенным открытым ключом. Здесь обе стороны локальны: создаём одноразовую учебную пару и уже знаем правильный открытый ключ. В реальной поставке источник доверия к ключу должен быть отдельным от скачанного архива.

Для примера нужен openssl и приложенный openssl.cnf. openssl_pkey_new создаёт RSA-пару, openssl_pkey_export возвращает закрытую PEM-строку в $private, get_details()["key"] даёт открытую PEM-часть. Закрытая часть не выводится и не сохраняется в документе. Phar::OPENSSL_SHA256 выбирает подпись с SHA256. Правильное имя файла открытого ключа — signed.phar.pubkey рядом с signed.phar.

Чтобы проверка действительно прочитала файл заново, reader.php запускается отдельным PHP-процессом: у Phar есть кеш контейнеров в памяти. proc_open получает массив аргументов, без shell-строки; PHP_BINARY выбирает тот же исполнитель, -c — ту же конфигурацию, -d включает readonly только читателю. Три pipe означают stdin/stdout/stderr. После чтения потоков проверяются пустой stderr и код завершения0.

reader.php:

<?php
try {
    $archive = new Phar(__DIR__ . '/signed.phar');
    echo "Доверенный в этом опыте ключ подтвердил поставку:\n";
    echo $archive['receipt.txt']->getContent();
} catch (UnexpectedValueException $error) {
    echo "Ключ не подтвердил поставку; документ не используется\n";
}

<?php
declare(strict_types=1);

$options = ['config' => __DIR__ . '/openssl.cnf', 'private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048];
$key = openssl_pkey_new($options);
if ($key === false || !openssl_pkey_export($key, $private, null, $options)) {
    throw new RuntimeException('Не создан учебный ключ');
}
$details = openssl_pkey_get_details($key);
if ($details === false) { throw new RuntimeException('Нет открытого ключа'); }
$path = __DIR__ . '/signed.phar';
file_put_contents($path . '.pubkey', $details['key']);
$archive = new Phar($path);
$archive->addFile(__DIR__ . '/input/receipt.txt', 'receipt.txt');
$archive->setSignatureAlgorithm(Phar::OPENSSL_SHA256, $private);
unset($archive);
function readInFreshProcess(): void {
    $command = [PHP_BINARY];
    $ini = php_ini_loaded_file();
    if ($ini !== false) { $command[] = '-c'; $command[] = $ini; }
    array_push($command, '-d', 'phar.readonly=1', __DIR__ . '/reader.php');
    $pipes = [];
    $process = proc_open($command, [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']], $pipes);
    if (!is_resource($process)) { throw new RuntimeException('Не запущен отдельный читатель'); }
    fclose($pipes[0]);
    $output = stream_get_contents($pipes[1]); fclose($pipes[1]);
    $errors = stream_get_contents($pipes[2]); fclose($pipes[2]);
    $exit = proc_close($process);
    if ($exit !== 0 || $errors !== '' || $output === false) { throw new RuntimeException('Ошибка процесса чтения'); }
    echo $output;
}
readInFreshProcess();
$otherKey = openssl_pkey_new($options);
if ($otherKey === false) { throw new RuntimeException('Нет другого учебного ключа'); }
$otherDetails = openssl_pkey_get_details($otherKey);
if ($otherDetails === false) { throw new RuntimeException('Нет другой открытой части'); }
file_put_contents($path . '.pubkey', $otherDetails['key']);
readInFreshProcess();
file_put_contents($path . '.pubkey', $details['key']);
echo "Правильный открытый ключ восстановлен для дальнейшего чтения\n";

Доверенный в этом опыте ключ подтвердил поставку:
Заказ 42
Кисть — 2 шт.
Итого: 300 руб.
Ключ не подтвердил поставку; документ не используется
Правильный открытый ключ восстановлен для дальнейшего чтения

Опубликованная рядом .pubkey сама по себе не подтверждает издателя: злоумышленник мог подменить оба файла. Закрепите доверенный ключ или проверяйте его по независимому каналу. Для получателя обычно сохраняют phar.readonly=1; подпись не делает безопасным неизвестное PHP-приложение.

Зачем нужны Phar и архивы данных

Программа и набор документов могут иметь один контейнер, но разные последствия использования. Наш TAR из первого урока читается как данные; app.phar из проекта запускает PHP. Нативный формат, TAR и ZIP поддерживают разные сочетания возможностей.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Как подготовить окружение

Сначала выясните, какой php.exe запускает сборку, затем проверьте загрузку Phar и нужных кодеков. php --ini показывает конфигурацию конкретного процесса; php --ri Phar — настройки расширения. Наличие Phar не отключает защиту записи исполняемых пакетов.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Зависимости сжатия и подписи

Обычный TAR читается без gzip/Bzip2. Для orders.tar.gz нужен zlib; для Bzip2 нужен bz2; для асимметричной подписи OpenSSL нужен openssl. Возможность чтения уже сжатых записей тоже зависит от декодера.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Встроенный модуль и отдельный процесс сборки

Phar входит в стандартную сборку PHP, но его могли отключить. Параметр --disable-phar относится к сборке самого PHP, а не к вашему example.php. Наши команды -d изменяют только один запуск и не требуют править серверный php.ini.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Три настройки: запись, обязательный хеш и кеш

phar.readonly=1 защищает создание/изменение исполняемого контейнера; обычный PharData остаётся доступен для данных. phar.require_hash проверяет присутствие механизма целостности, но не доверие издателю. phar.cache_list загружает указанные архивы при старте процесса; менять кешируемую поставку во время работы не следует.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Поток phar:// и объекты

fopen возвращает поток, который закрывают fclose; Phar представляет весь контейнер, PharFileInfo — одну запись. Эти объекты и ресурс потока выполняют разные задачи. phar:// путь внутри архива отличается от пути orders.phar на диске.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Константы по задачам

Phar::TAR выбирает формат, Phar::GZ — алгоритм сжатия, Phar::SHA256 — проверку целостности. Одинаково выглядящие целые значения из разных групп не взаимозаменяемы: методу передают константу его категории. OPENSSL_SHA256 и OPENSSL_SHA512 — отдельные алгоритмы подписи, а PHP/PHPS относятся только к MIME-маршрутизации webPhar.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Как использовать готовый контейнер

Для документа читаем запись через объект/поток; для проверенной программы запускаем собственный stub. Путь выполнения и нужное доверие выбирают до вызова require. Два полных проекта выше демонстрируют оба пути.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

От чтения файла к запуску пакета

Здесь собраны все способы применения: запуск CLI, подключение библиотеки, обход записей, буферизация, метаданные, подпись и веб-маршрутизация. Старые условные примеры с чужими архивами заменены нашим app.phar и localhost-проектом. Буферизацию не следует понимать как транзакцию базы данных: rollback в этом API нет.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Читать запись без извлечения

В проекте receiveDocuments поток читает только разрешённую запись и не более1025байт. phar:// работает локально даже при отключённых allow_url_fopen/include; эта возможность не разрешает выполнять недоверенный код. Для создания удобнее объектный API. Режим append обёрткой не поддерживается.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Уточнение вызова file_put_contents: потоковый context — четвёртый аргумент, после flags. В нашем расширенном примере использованы file_put_contents($url, $text, 0, $context) и параметры phar.compress/phar.metadata; старую условную иллюстрацию с тремя аргументами не следует копировать.

Три класса и квадратные скобки

Phar/PharData управляют контейнером, а $archive["receipt.txt"] возвращает PharFileInfo. При присваивании тем же скобкам вызывается offsetSet, при isset — offsetExists, при unset — offsetUnset. Для передачи источника можно использовать строку или открытый поток; для обхода деревьев — SPL-итератор.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

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

Последовательность собственной сборки

Задайте точный состав, создайте новый контейнер, добавьте собственные файлы, установите stub, завершите запись и запустите готовый результат. Ошибка любого этапа означает незавершённую сборку, которую нельзя выдавать как готовую программу.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Отсутствующий в старой документации учебный путь

Официальная страница содержит только направления чтения. Здесь полный недостающий путь уже представлен: source/main.php + source/stub.php + input/receipt.txt → сборщик → app.phar → реальный вывод чека. Для большого набора файлов изучите buildFromDirectory/buildFromIterator, для веб-программы — webPhar.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Почему Phar может быть TAR или ZIP

Формат контейнера и исполняемость не одно и то же. Обычный orders.tar — данные; TAR с загрузчиком и правилами именования может быть исполняемым Phar. Конвертация создаёт новый файл, исходник сохраняется.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Из чего состоит исполняемый контейнер

Stub задаёт начало программы, манифест описывает записи, дальше идут их байты и данные целостности. Для данных TAR/ZIP загрузчик отсутствует. Утверждение старой краткой страницы о подписи только нативного формата ограничено историческим описанием: современная сравнительная таблица и реализация поддерживают подписи также TAR/ZIP.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Граница PHP-загрузчика и бинарных данных

Минимальный stub — <?php __HALT_COMPILER();. Наш полноценный stub дополнительно регистрирует контейнер и запускает main.php. Маркер завершения обязателен; обычный текст после него относится уже к контейнеру, поэтому строку загрузчика нельзя конструировать из пользовательского ввода.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

?>

?>

Выбор формата по нужной операции

Нужно отдельно сжимать записи — выбирайте PHAR/ZIP. Нужен обычный TAR.GZ — сжимайте TAR целиком. Нужна запись данных при phar.readonly=1 — используйте PharData без исполняемого stub. Таблица ниже сохраняет каждое официальное отличие и оговорку.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

TAR: последовательный контейнер и сжатие целиком

Наш orders.tar.gz содержит два документа, а не два отдельных gzip-потока. Для USTAR важны длины путей; PAX/GNU-расширения поддерживаются ограниченно. Это следует проверить до выбора TAR для чужого экспорта.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

ZIP: записи, комментарии и метаданные

В ZIP отдельные документы могут иметь собственное сжатие. Phar хранит PHP-метаданные в комментариях; такой комментарий не обязан быть привычной человеку заметкой архиватора. При обмене с другими инструментами лучше явная JSON-запись с заданной схемой.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Нативный манифест: длины, версия и порядок байтов

Эта таблица нужна разработчику инструментов формата, а не первому сборщику: обычное приложение не вычисляет смещения вручную. Указание «текущая1.0.0» в исторической таблице нельзя принимать за нынешнюю версию: apiVersion/getVersion читают реальное значение; пустые директории требуют1.1.1.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Общие флаги всего контейнера

Бит подписи и наличие хотя бы одной сжатой записи относятся к архиву в целом. Это не права доступа отдельного чека и не произвольное место для пользовательских данных. Собственные сведения хранят в метаданных или отдельном документе.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Одна запись манифеста: что описывает receipt.txt

Размер до сжатия, время, размер хранения, CRC и флаги описывают конкретный документ. Большое заявленное число не разрешает программе выделять столько памяти: импорт проверяет и метаданные, и фактические прочитанные байты.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Подпись в конце файла и доверенный издатель

MD5/SHA-хеши — контроль повреждения. Для удостоверения автора нужна асимметричная подпись и доверенный открытый ключ. Ключ рядом с архивом не становится доверенным только из-за имени .pubkey. Актуальные OPENSSL_SHA256/OPENSSL_SHA512 дополняют исторический OPENSSL.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Класс Phar и унаследованные возможности

Phar расширяет RecursiveDirectoryIterator, поддерживает Countable и ArrayAccess. Ниже сохранён полный официальный обзор, включая унаследованные методы и константы; собственные96API разобраны индивидуально. Родительский итератор нужен для обхода, а методы Phar — для изменения контейнера.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Класс PharData для неисполняемых данных

PharData наследует Phar, но снимает ограничение readonly для обычных TAR/ZIP. setAlias/setStub/setDefaultStub намеренно отказывают: эти операции относятся к исполняемому контейнеру. Наследование сигнатуры не гарантирует одинаковый смысл у подкласса.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

Класс PharFileInfo для одной записи

PharFileInfo расширяет SplFileInfo: обычные сведения о файле сочетаются с getContent, сжатием, CRC и метаданными. Экземпляр получают через $archive["receipt.txt"], поэтому сначала необходим открытый контейнер и существующее имя.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.

PharException и другие причины отказа

PharException наследует Exception. Некоторые проверки API бросают также UnexpectedValueException/BadMethodCallException; ловить только PharException для всей сборки недостаточно. Отказ нельзя превращать в сообщение об успешной поставке; сохраняйте диагностику и оставляйте прежний результат.

Связный пример с полными файлами: показать путь от входа к результату.

Официальный контракт: адаптированная русская документация PHP Documentation Group, CC BY 3.0 или более поздняя версия. Изменены оформление и внутренние ссылки; условные иллюстрации заменены самостоятельными учебными проектами. Сигнатуры сверены с английской редакцией; уточнения версий отмечены отдельно.