PHP 8.5: CLI/CGI: Удалён параметр `-z` / `--zend-extension`

До PHP 8.5 в справке исполняемого файла PHP (php --help / php -h) указывалось, что поддерживается опция -z для загрузки расширения Zend перед выполнением заданного файла или запуском интерпретатора.

php --help

Usage: php [options] [-f] <file> [--] [args...]
   php [options] -r <code> [--] [args...]
   php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
   php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
   php [options] -S <addr>:<port> [-t docroot] [router]
   php [options] -- [args...]
   php [options] -a

  -a               Run as interactive shell (requires readline extension)
...
  -z <file>        Load Zend extension <file>
...

Опция -z также имеет более длинный псевдоним --zend-extension.

PHP 8.5 оба параметра -z и --zend-extension окончательно удалены. Это изменение — финальный шаг в устранении давно сломанной функциональности: опция -z не работала корректно для загрузки Zend-расширений как минимум на протяжении последних нескольких основных релизов PHP (например, в ветках 8.x и 7.x), а её реализация в CLI/CGI SAPI всегда была неполноценной.

Например, команда ниже попытается загрузить расширение Opcache (opcache.so) с помощью параметра -z. Однако, как видно из вывода -m, расширение не загружается и отсутствует в списке активных модулей, что и демонстрирует неработоспособность опции.

$ php -z /usr/lib/php/20240924/opcache.so -m | grep -i opcache
# Ничего не выведется, opcache не загружен

Рекомендуемая замена

Рекомендации зависят от того, какую цель преследовало использование -z.

1. Если опция -z использовалась формально или «по наследству» от старой кодовой базы, но фактическая загрузка расширения не требовалась. Вы можете безопасно удалить параметр -z (или --zend-extension) и его значение из командной строки, конфигураций или скриптов. Поскольку опция давно не выполняла свою функцию, её удаление не изменит фактическое поведение скрипта в версиях PHP 8.5 и старше.
2. Если требуется именно загрузить Zend-расширение (например, Xdebug для отладки). В этом случае необходимо заменить неработающий параметр -z на установку директивы zend_extension с помощью параметра -d. Этот метод является корректным и поддерживается всеми версиями PHP.

-php -z xdebug.so my-script.php
+php -d zend_extension=xdebug.so my-script.php

Обратите внимание, что опцию -d можно использовать многократно для загрузки нескольких расширений.

Как найти использования опции -z

Рекомендуем провести поиск по кодовой базе:

# Поиск короткой формы (-z)
grep -r "\-z\b" /path/to/project/
# /path/to/project/deploy.sh: php -z opcache.so composer install
# /path/to/project/scripts/run.sh: php -z ./ext/xdebug.so test.php
# /path/to/project/Dockerfile: RUN php -z /usr/local/lib/php/extensions/my_ext.so artisan optimize

# Поиск длинной формы (--zend-extension)
grep -r "\-\-zend-extension" /path/to/project/
# /path/to/project/docker-compose.yml: command: php --zend-extension=xdebug.so -S 0.0.0.0:80
# /path/to/project/.platform/hooks/postdeploy.sh: php --zend-extension=/opt/remi/php85/root/usr/lib64/php/modules/opcache.so vendor/bin/phpunit
# /path/to/project/makefile:  php --zend-extension=blackfire.so $(SCRIPT)

Краткий итог:

• Опция -z была сломана годами и окончательно удалена в PHP 8.5.
• Если она использовалась формально — просто удалите её.
• Если нужно загрузить расширение — используйте -d zend_extension=....
• Проверьте свой код с помощью grep, чтобы не пропустить использования.