Настройка PHP модулей при развертывании веб-сервера

Раздел: Администрирование -> Установка веб-сервера

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

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

Способ 1. Установка через пакетный менеджер

Этот метод подходит для дистрибутивов Linux на основе Debian/Ubuntu (apt) и Red Hat/CentOS (yum/dnf). Расширения поставляются в виде отдельных пакетов, которые интегрируются с системным PHP.

Пример для Ubuntu/Debian с PHP 8.2:

sudo apt update
sudo apt install php8.2-mbstring php8.2-curl php8.2-gd php8.2-xml php8.2-mysql

установка php 7.4 (установка php версии 7.4)

Для CentOS/RHEL с PHP 8.2 (после подключения репозитория EPEL и Remi):

sudo dnf install php82-php-mbstring php82-php-curl php82-php-gd php82-php-xml php82-php-mysqlnd

установка php расширений (установка расширений php)

После установки необходимо перезагрузить веб-сервер (Apache или Nginx + PHP-FPM) командой:

sudo systemctl restart apache2   # для Apache
sudo systemctl restart php8.2-fpm # для PHP-FPM

Типичные ошибки:

  • Пакет не найден: "Unable to locate package php8.2-mbstring". Решение: обновить список пакетов (sudo apt update), проверить версию PHP, подключить сторонний репозиторий (например, ondrej/php для Ubuntu).
  • Конфликт версий: установка расширения для другой версии PHP (например, php7.4-mbstring при PHP 8.2). Решение: явно указывать версию в имени пакета (php8.2-*).
  • После установки расширение не загружается: проверить, что файл .so находится в директории extension_dir (php -i | grep extension_dir) и что в php.ini нет закомментированной строки extension=... Включить отображение ошибок PHP.

Как установить расширение из репозитория PECL?

Для расширений, которых нет в системных репозиториях (например, redis, imagick, xdebug), используется менеджер pecl. Требуется установить PHP и инструменты разработки.

Установка pecl (обычно входит в пакет php-dev или php-pear):

sudo apt install php8.2-dev php-pear  # для Ubuntu
sudo dnf install php82-php-devel        # для CentOS

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

sudo pecl install redis

После установки добавить в php.ini строку (путь может отличаться):

extension=redis.so

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

php -m | grep redis

Проблемы:

  • Ошибка "phpize not found": установить php-dev.
  • Не удаётся найти пакет: проверить доступные версии через pecl list-all или указать версию: sudo pecl install redis-5.3.7.
  • Конфликт с системным менеджером: если расширение уже установлено через apt, pecl может отказаться устанавливать. Удалить пакетную версию.

Как установить расширение с нестандартными параметрами сборки?

Если расширение не доступно ни в пакетах, ни в PECL, или требуется особая конфигурация, можно скомпилировать из исходного кода.

Пример для расширения swoole:

# Установка зависимостей
sudo apt install php8.2-dev libswoole-dev libcurl4-openssl-dev
# Скачивание исходников
cd /tmp
git clone https://github.com/swoole/swoole-src.git
cd swoole-src
phpize
./configure --enable-openssl --enable-http2
make -j$(nproc)
sudo make install

Добавить в php.ini:

extension=swoole.so

Проблемы:

  • Ошибка компиляции из-за отсутствия библиотек: установить все зависимости, указанные в документации расширения.
  • Несовместимость с версией PHP: проверить, что расширение поддерживает текущую версию PHP.
  • Некорректные пути: после make install может потребоваться вручную скопировать swoole.so в директорию расширений (php -i | grep extension_dir).

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

Для контейнерных сред используется встроенный скрипт docker-php-ext-install, который автоматизирует установку.

Пример Dockerfile:

FROM php:8.2-fpm
RUN apt update && apt install -y libpq-dev && \
    docker-php-ext-install pdo pdo_mysql mysqli
# Для расширений из PECL:
RUN pecl install xdebug && docker-php-ext-enable xdebug

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

docker build -t my-php-app .

Проблемы:

  • Ошибка "docker-php-ext-install not found": используется только в официальных образах PHP от Docker. Для других образов потребуется ручная установка.
  • Нехватка памяти при сборке: использовать docker build --memory=... или увеличить swap.
  • Отсутствие libpq-dev для pdo_pgsql: установить необходимые dev-пакеты до вызова docker-php-ext-install.

Как включить расширение, которое уже установлено, но не активно?

Некоторые расширения (opcache, json, session) встроены в PHP, но могут быть отключены в php.ini. Для включения достаточно раскомментировать или добавить строку.

Найти php.ini:

php --ini

Открыть файл, найти строку ;extension=opcache и убрать точку с запятой:

extension=opcache

Для встроенных расширений не нужно указывать путь, они уже скомпилированы.

Проблемы:

  • Изменения не вступают в силу: перезагрузить веб-сервер или PHP-FPM.
  • Расширение не найдено: проверить, что файл .so существует или что расширение действительно встроено (php -m покажет).

Расширенные примеры и команды

Дополнительные сценарии установки и проверки расширений PHP.

Пример 
sudo apt install php8.2-{bcmath,bz2,calendar,ctype,curl,dba,dom,enchant,exif,fileinfo,filter,ftp,gd,gettext,gmp,iconv,imap,intl,json,ldap,mbstring,mysqli,oci8,odbc,opcache,pcntl,pdo,pdo_dblib,pdo_firebird,pdo_mysql,pdo_oci,pdo_odbc,pdo_pgsql,pdo_sqlite,pgsql,phar,posix,pspell,readline,recode,shmop,simplexml,soap,sockets,spl,standard,sysvmsg,sysvsem,sysvshm,tidy,tokenizer,wddx,xml,xmlreader,xmlwriter,xsl,zip}
Установка всех доступных расширений PHP 8.2 одной командой с помощью фигурных скобок оболочки.
Пример 
# Список доступных версий
sudo pecl list-all | grep redis
# Установка версии 5.3.7
sudo pecl install redis-5.3.7
Команды для просмотра и установки определенной версии расширения redis.
Пример 
# Установка зависимостей для imagick
sudo apt install libmagickwand-dev
# Скачивание последней версии PECL imagick
sudo pecl download imagick-3.7.0
tar xzf imagick-3.7.0.tgz
cd imagick-3.7.0
phpize
./configure --with-imagick=/usr/local
make -j4
sudo make install
# Добавление в php.ini
echo 'extension=imagick.so' | sudo tee -a /etc/php/8.2/cli/conf.d/imagick.ini
# Проверка
php -m | grep imagick
Успешная установка imagick из исходников.
Пример 
FROM php:8.3-cli
# Установка системных зависимостей
RUN apt update && apt install -y libzip-dev libpng-dev libjpeg-dev libfreetype6-dev
# Установка расширений через docker-php-ext-install
RUN docker-php-ext-configure gd --with-freetype --with-jpeg && \
    docker-php-ext-install gd zip pcntl bcmath
# Установка через pecl
RUN pecl install redis && docker-php-ext-enable redis
# Копирование приложения
COPY . /app
WORKDIR /app
CMD ["php", "index.php"]
Многоступенчатая сборка образа с PHP 8.3, расширениями и приложением.
Пример 
php -m
# Фильтрация по части имени
php -m | grep -i "mysql\|pdo\|curl"
Вывод списка всех расширений и выборочная фильтрация.
Пример 
# Создать файл /etc/php/8.2/mods-available/redis.ini
echo 'extension=redis.so' | sudo tee /etc/php/8.2/mods-available/redis.ini
# Включить модуль для CLI и FPM
sudo phpenmod -v 8.2 redis
# Проверка
php -m | grep redis
Использование phpenmod для управления модулями в Debian/Ubuntu.
Пример 
<?php
phpinfo();
?>
Страница с полной информацией о PHP включает раздел "mbstring" или "redis" если расширение установлено.

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

En
установка php расширений (php)