Встановлення розширень PHP на Ubuntu та Debian

Типи PHP-розширень

PHP-розширення розширюють можливості мови: додають підтримку баз даних, зображень, криптографії, мережевих протоколів. Існує два типи: вбудовані (ідуть у комплекті з PHP) та PECL-розширення (встановлюються окремо через pecl чи apt).

Перегляд встановлених розширень

# Список усіх завантажених розширень
php -m

# Перевірити конкретне розширення
php -m | grep curl

# Детальна інформація
php --ri gd

Встановлення розширень через apt

# Оновлюємо список пакетів
sudo apt update

# Встановлюємо розширення для PHP 8.2
sudo apt install php8.2-curl php8.2-gd php8.2-mbstring php8.2-xml \
    php8.2-zip php8.2-mysql php8.2-pgsql php8.2-redis \
    php8.2-imagick php8.2-intl php8.2-bcmath php8.2-soap

# Перезапускаємо PHP-FPM
sudo systemctl restart php8.2-fpm

Необхідні розширення для популярних CMS

Встановлення PECL-розширень (Redis, Imagick)

# Redis через apt (рекомендовано)
sudo apt install php8.2-redis

# Imagick
sudo apt install php8.2-imagick

# Через PECL (якщо немає в apt)
sudo pecl install redis
echo "extension=redis.so" | sudo tee /etc/php/8.2/mods-available/redis.ini
sudo phpenmod redis

Керування розширеннями: phpenmod / phpdismod

# Увімкнути розширення
sudo phpenmod -s fpm mbstring

# Вимкнути розширення
sudo phpdismod -s fpm xdebug

# Застосувати зміни
sudo systemctl reload php8.2-fpm

Компіляція розширення з вихідних кодів

sudo apt install php8.2-dev
pecl download xdebug
tar xf xdebug-*.tgz && cd xdebug-*
phpize && ./configure --with-php-config=/usr/bin/php-config8.2
make && sudo make install

Типові помилки без потрібного розширення

Call to undefined function

PHP Fatal error:  Uncaught Error: Call to undefined function curl_init() in /var/www/html/vendor/guzzlehttp/guzzle/src/Handler/CurlHandler.php:1

Означає, що розширення curl не встановлено взагалі, або встановлено, але не увімкнено для того SAPI, який реально обслуговує запит. CLI і FPM однієї версії PHP використовують окремі каталоги conf.d, і список модулів у них може відрізнятися.

could not find driver (PDO)

PDOException: could not find driver in /var/www/html/app/Database.php:14

Часта помилка новачків: розширення pdo встановлено, а конкретний драйвер — pdo_mysql чи pdo_pgsql — ні. Це два різні пакети в apt.

Class "Imagick" not found

Fatal error: Uncaught Error: Class "Imagick" not found in /var/www/html/app/Thumbnail.php:9

PECL-розширення встановлено, але не активовано, або активовано лише для одного з SAPI.

Коли встановлення через apt недостатньо

• Розширення увімкнено для CLI, але не для FPM (або навпаки) — керування модулями роздільне: phpenmod -s fpm curl і phpenmod -s cli curl — різні команди.
• Після apt install php8.2-imagick забули перезапустити FPM — модуль підвантажується в пам'ять процесу лише під час його старту, простого reload Nginx недостатньо.
• Версія розширення з репозиторію ondrej/php ще не зібрана під найновішу версію PHP — тоді лишається або чекати оновлення пакета, або збирати з вихідних кодів.
• Сайт використовує кілька версій PHP одночасно — розширення потрібно ставити під кожну версію окремо, apt не робить це автоматично.

Перевірка результату

# Розширення взагалі видно інтерпретатору?
php -m | grep -i curl

# Явна перевірка з коду — надійніше за grep
php -r "var_dump(extension_loaded('curl'));"

# Те саме, але для PHP-FPM: створіть info.php з phpinfo()
# і шукайте секцію розширення у виводі браузера — список модулів
# CLI і FPM показується там окремо і може відрізнятися

Якщо php -m показує модуль, а код усе одно падає з «Call to undefined function» — майже напевно ви перевіряли CLI, а помилка приходить із FPM (або навпаки).

Ще одне джерело плутанини — розширення, зібрані вручну з вихідних кодів: вони кладуться не в /etc/php/8.2/mods-available/, а туди, куди вказали при збірці, і phpenmod про них нічого не знає. Такі модулі потрібно підключати вручну директивою extension= в окремому ini-файлі та вмикати її в потрібний конфіг SAPI руками, без автоматизації apt.

Після оновлення системи через apt upgrade модулі, зібрані з вихідних кодів, не оновлюються разом із пакетним PHP — під час переходу на нову мінорну версію їх доведеться перезбирати заново, інакше після перезапуску FPM з'явиться помилка про несумісну версію API модуля.