Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Устанавливает в Phar-архив заглушку, которая играет роль начального загрузчика PHP

Описание

public function Phar::setStub(resource|string $stub, int $length = -1): true

Замечание: Для корректной работы метода с объектами Phar потребуется установить для директивы phar.readonly в файле php.ini значение 0, иначе метод выбросит исключение PharException.

Метод устанавливает заглушку — начальный загрузчик — в Phar-архив: в новый архив добавляет, а в текущем — заменяет.

Загрузочная заглушка срабатывает при каждом включении Phar-архива:

<?php

include 'myphar.phar';

и при выполнении из командной строки:

php myphar.phar

При включении файла через потоковую обёртку phar загрузчик не запускается:

<?php

include 'phar://myphar.phar/somefile.php';

Список параметров

stub: Строка или дескриптор открытого потока; при включении архива код заглушки выполняется как начальный загрузчик.
length: Количество байтов, которое требуется прочитать из потока; параметр учитывается, только если в аргументе stub передали ресурс.
Внимание
С PHP 8.3.0 вызов метода с ресурсом (resource) в первом аргументе УСТАРЕЛ, поэтому вместо передачи ресурса и аргумента length теперь вызывают: $phar->setStub(stream_get_contents($resource)).

Возвращаемые значения

Функция возвращает логическое значение true.

Ошибки

При вызове метода с включённой в файле php.ini директивой phar.readonly выбрасывается исключение UnexpectedValueException. При ошибке сброса изменений на диск выбрасывается исключение PharException.

Список изменений

Версия	Описание
8.4.0	Вместо общего логического типа bool теперь возвращается конкретный тип `true`.
8.3.0	Вызов метода Phar::setStub() с ресурсом (resource) в первом аргументе УСТАРЕЛ. Вместо передачи ресурса и аргумента `length` теперь вызывают: `$phar->setStub(stream_get_contents($resource));`.

Примеры

Пример #1 Пример установки начальной загрузочной заглушки методом Phar::setStub()

<?php

try {
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');

    $p['a.php'] = '<?php var_dump("Привет,");';
    $p->setStub('<?php var_dump("Первый загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/a.php';
    var_dump($p->getStub());

    $p['b.php'] = '<?php var_dump(" мир!");';
    $p->setStub('<?php var_dump("Второй загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
    include 'phar://brandnewphar.phar/b.php';
    var_dump($p->getStub());
} catch (Exception $e) {
    echo 'При записи операций в архив brandnewphar.phar возникла ошибка: ', $e;
}

Результат выполнения приведённого примера:

string(13) "Привет,"
string(108) "<?php var_dump("Первый загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(8) " мир!"
string(108) "<?php var_dump("Второй загрузчик"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

Смотрите также

Phar::getStub() - Получить загрузчик PHP или загрузчик заглушки Phar-архива
Phar::createDefaultStub() - Создать заглушку в формате phar-архива