Способы инсталляции PHP-расширений

Раздел: Расширения PHP -> Управление расширениями PHP

Способы установки расширений PHP

Как установить расширение PHP с помощью менеджера пакетов PECL?

Основной и наиболее универсальный способ

PECL (PHP Extension Community Library) позволяет загружать и компилировать расширения прямо из официального репозитория. Этот метод подходит для большинства платформ (Linux, macOS, Windows через WSL) и не требует ручной сборки зависимостей, если они доступны в системе.

Пример установки расширения xdebug:

sudo pecl install xdebug

Off php ext (отключение расширения php)

После завершения установки необходимо добавить строку extension=xdebug.so (или zend_extension=xdebug.so) в конец файла php.ini. Местоположение файла можно узнать командой:

php --ini

Ext http php (расширение http для php)

Затем следует перезапустить веб-сервер (Apache, Nginx с PHP-FPM) или CLI-сессию. Проверка подключения расширения:

php -m | grep xdebug

Ext php install (установка расширения php)

Цели и случаи использования: PECL идеален для установки популярных расширений, таких как xdebug, redis, mongodb, imagick. Он автоматически загружает зависимости через compose (если они описаны в package.xml) и требует минимальных действий.

Типичные проблемы и их решение

Ошибка компиляции (ошибка при выполнении phpize или make) – обычно не хватает заголовочных файлов PHP или системных библиотек. Решение: установить пакет php-dev (или php-X.Y-dev) и build-essential (gcc, make).
Требуются права суперпользователя – используйте sudo перед командой pecl.
Расширение уже установлено – pecl сообщит об этом. Можно принудительно переустановить с флагом -f.

Как установить расширение PHP через системный пакетный менеджер (apt, yum)?

Данный способ наиболее прост для пользователей Debian/Ubuntu или CentOS/RHEL. Расширения упакованы в виде отдельных пакетов с именем вида php-{имя_расширения} или php{X.Y}-{имя_расширения}.

Пример для Ubuntu (установка расширения MySQL):

sudo apt update
sudo apt install php-mysql

Docker php ext (расширение php в docker)

На CentOS (с репозиторием Remi или EPEL):

sudo yum install php-pdo php-mysqlnd

После установки пакет автоматически активируется в php.ini (обычно через файл в /etc/php/{version}/mods-available/ с последующей символьной ссылкой). Проверка: php -m.

Цели и случаи использования: Рекомендуется для стабильных окружений на выделенных серверах или VPS, где версия PHP фиксирована и не требует ручной компиляции. Подходит для стандартных расширений (mysql, xml, mbstring, gd).

Типичные проблемы и их решение

Пакет не найден – возможно, расширение не входит в стандартный репозиторий. Добавить сторонний репозиторий (например, Ondrej PPA для Ubuntu) или установить конкретную версию, например php7.4-mysql.
Версия пакета не соответствует версии PHP – указывайте явно php8.1-mysql.
После установки расширение не отображается – проверьте наличие файла *.ini в /etc/php/*/conf.d/ и перезапустите PHP-FPM (systemctl restart php*-fpm).

Как собрать расширение PHP из исходного кода с помощью phpize?

Этот метод необходим, если расширения нет в PECL или системном репозитории, либо требуется нестандартная конфигурация. Подразумевает ручную компиляцию.

Пример сборки расширения apcu (если оно не установлено иным способом):

Скачать исходники (например, с GitHub): git clone https://github.com/krakjoe/apcu.git
Перейти в каталог расширения: cd apcu
Запустить phpize (этот скрипт создаёт окружение для сборки): phpize
Настроить сборку: ./configure
Скомпилировать: make
Установить модуль в каталог расширений: sudo make install
Добавить extension=apcu.so в php.ini.

Цели и случаи использования: Сборка из исходников полезна для экспериментальных или редко используемых расширений, для настройки расширения с особыми флагами (например, отключение части функциональности) или для версий, не совместимых с текущим дистрибутивом.

Типичные проблемы и их решение

phpize: command not found – не установлен пакет php-dev (или php-X.Y-dev).
configure: error: missing dependency – необходимо установить соответствующую библиотеку (например, libcurl-dev для curl).
make: ошибка компиляции – проверьте версию компилятора и заголовки PHP. Иногда помогает очистка make clean и повтор make.

Как активировать встроенное расширение PHP без установки?

Часть расширений уже скомпилирована в исполняемый файл PHP, но отключена (закомментирована) в php.ini. Для их активации достаточно удалить точку с запятой перед строкой extension=название.

Пример с расширением mysqli:

;extension=mysqli   ->   extension=mysqli

После изменения сохранить файл и перезапустить сервер.

Цели и случаи использования: Быстрая настройка окружения, когда расширение уже присутствует в системе, но не активно. Особенно актуально для стандартных библиотек (mysqli, pdo_mysql, json, mbstring).

Типичные проблемы и их решение

Расширение не скомпилировано вообще – если в php.ini нет строки даже закомментированной, значит модуль не встроен. Требуется другой способ установки.
После включения появляется ошибка – возможно, не хватает зависимостей на уровне ОС (например, для gd нужна libgd).

Как добавить расширение PHP в Docker-образ?

В контейнерных средах обычно используется базовый образ php:X.Y из Docker Hub. Встроенная утилита docker-php-ext-install упрощает установку расширений.

Пример Dockerfile для установки pdo_mysql и bcmath:

FROM php:8.2-cli
RUN docker-php-ext-install pdo_mysql bcmath

Для расширений, требующих системных зависимостей, сначала нужно их установить:

RUN apt-get update && apt-get install -y libicu-dev \
    && docker-php-ext-install intl

Проверка внутри контейнера: php -m.

Цели и случаи использования: Идеально для контейнеризированных приложений, микросервисов или локальной разработки с Docker. Позволяет изолировать версии расширений и не загрязнять хост-систему.

Типичные проблемы и их решение

docker-php-ext-install: command not found – образ не основан на официальном php; используйте php:X.Y.
Расширение требует установки дополнительных пакетов – необходимо добавить RUN apt-get install ... перед docker-php-ext-install.
Ошибка компиляции внутри контейнера – убедитесь, что в образе присутствуют gcc, make (обычно они есть).

Расширенные примеры установки расширений PHP

Ниже приведены более сложные сценарии с кодом и результатами.

Пример 1: Установка xdebug через PECL с конфигурацией для отладки

Команды:

Пример

sudo pecl install xdebug-3.3.2
# Добавить в php.ini:
zend_extension=/usr/lib/php/20230831/xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes

Проверка результата:

$ php -v
PHP 8.2.17 (cli) (built: Feb 14 2024 14:02:50) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.2.17, Copyright (c) Zend Technologies
    with Xdebug v3.3.2, Copyright (c) 2002-2024, by Derick Rethans

Пример 2: Сборка расширения imagick из исходников с системными библиотеками

Предварительно установить ImageMagick:

Пример

sudo apt install libmagickwand-dev libmagickcore-dev
# Клонирование и сборка
git clone https://github.com/Imagick/imagick.git
cd imagick
phpize
./configure --with-imagick=/usr/local
make -j$(nproc)
sudo make install
# Добавление в php.ini: extension=imagick.so

Проверка:

$ php -r "echo extension_loaded('imagick') ? 'loaded' : 'missing';"
loaded

Пример 3: Dockerfile для установки расширения apcu и opcache с настройкой

Пример

FROM php:8.2-apache
RUN docker-php-ext-install opcache \
    && pecl install apcu \
    && docker-php-ext-enable apcu
COPY opcache.ini /usr/local/etc/php/conf.d/opcache.ini

Содержимое файла opcache.ini:

Пример

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000

Сборка образа:

Пример

docker build -t my-php-app .

Проверка расширений внутри контейнера:

$ docker run --rm my-php-app php -m
[PHP Modules]
Core
...
apcu
opcache
...

Пример 4: Автоматическое включение всех встроенных расширений в php.ini через sed

Пример

sed -i 's/;extension=/extension=/g' /etc/php/8.2/cli/php.ini

Однако это может включить нежелательные модули. Лучше точечно:

Пример

for ext in mysqli pdo_mysql xmlrpc; do
  sed -i "s/;extension=$ext/extension=$ext/" /etc/php/8.2/cli/php.ini
done

После этого выполнить php -m | grep -E 'mysqli|pdo_mysql|xmlrpc' для проверки.

Пример 5: Установка нескольких расширений через pecl с автоматической загрузкой зависимостей (imagick, redis, mongodb)

Пример

sudo apt install -y libmagickwand-dev libssl-dev libcurl4-openssl-dev
sudo pecl install imagick redis mongodb

Возможный вывод при установке redis:

downloading redis-6.1.0.tgz ...
...
compiling...
installing...
install ok: channel://pecl.php.net/redis-6.1.0

После установки добавить строки в php.ini или создать отдельные файлы .ini в папке conf.d.

Установка расширения PHP - comments

Ext php install (php)