PHP : dépannage

Premiers réflexes

php --version
php -m | sort | head -40
php --ini
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50 --no-pager
sudo tail -n 50 /var/log/nginx/error.log          # ou le journal du serveur web utilisé
sudo tail -n 50 /var/log/php_erreurs.log

Remplacer 8.3 par 8.5 sur Ubuntu 26.04 (systemctl list-units 'php*-fpm*' donne le nom exact).

Erreurs fréquentes

Symptôme	Cause et solution
Page blanche (erreur 500)	Erreur fatale masquée : lire le journal PHP et celui du serveur web
502 Bad Gateway	PHP-FPM arrêté ou socket incorrect : voir PHP-FPM et serveur web
Le fichier .php est téléchargé ou affiché en clair	PHP non branché au serveur web
Call to undefined function …	Extension manquante : apt search php-<nom> puis installation
Class "…" not found	Autoload : composer dump-autoload
Allowed memory size … exhausted	memory_limit ou fuite mémoire
Maximum execution time exceeded	Script trop long : max_execution_time ou passage en CLI
Permission denied à l’écriture	Dossier non modifiable par www-data (voir plus bas)
Headers already sent	Sortie avant header() ou session_start() : espace ou ligne vide avant <?php
Cannot modify header information	Même cause
Modification du code sans effet	OPcache avec validate_timestamps = 0 : recharger PHP-FPM

Droits de fichiers

ps -o user= -C php-fpm8.3 | sort -u               # utilisateur des processus PHP
namei -l /var/www/monapp/var/cache                # droits de chaque dossier du chemin
sudo -u www-data test -w /var/www/monapp/var && echo "écriture possible"

Le chemin complet doit être traversable (x sur chaque dossier parent).

Erreurs de version

php -r 'echo PHP_VERSION, "\n";'
composer check-platform-reqs
php -l fichier.php                              # vérifie la syntaxe

Un code écrit pour 8.3 peut afficher des avertissements de dépréciation en 8.5 : les repérer avec error_reporting = E_ALL et un journal d’erreurs, puis corriger avant de migrer.

Déboguer

Sans outil : var_dump($valeur), error_log(print_r($valeur, true)).

Avec Xdebug (développement uniquement) :

sudo apt install php-xdebug
php -v                                           # mentionne Xdebug si activé

/etc/php/8.3/mods-available/xdebug.ini :

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=trigger

Désactiver Xdebug en production : il ralentit sensiblement PHP (sudo phpdismod xdebug).

Lenteurs

php -r 'var_dump(opcache_get_status(false)["opcache_enabled"] ?? false);'
sudo tail -n 20 /var/log/php8.3-fpm.log                 # « server reached pm.max_children »
ps -ylC php-fpm8.3 --sort:rss | head

Pistes : OPcache actif, pm.max_children adapté, requêtes SQL lentes (voir MariaDB : index et performances), dépendances inutiles (composer install --no-dev --optimize-autoloader).

Activer le journal des requêtes lentes de PHP-FPM, dans le pool :

slowlog = /var/log/php8.3-fpm-lent.log
request_slowlog_timeout = 5s

Mettre à jour en sécurité

1. Sauvegarder le code et la base.
2. Lire le guide de migration de la version visée.
3. Tester sur une copie avec error_reporting = E_ALL.
4. Mettre à jour, puis recharger PHP-FPM et surveiller les journaux.

Ubuntu 24.04 et 26.04 : différences à connaître

Les diagnostics sont les mêmes sur les deux versions ; adapter les noms de service et de journal à la version (php8.3-fpm, php8.5-fpm).

Pour aller plus loin

• Liste des erreurs PHP
• Retour : Installation

Dans la même rubrique

• Installation
• Premiers pas
• Composer
• PHP-FPM et serveur web
• Configuration
• Bases de données avec PDO
• Dépannage