PHP 8.5 avec Laravel Octane et FrankenPHP : manuel de mise en route

Le binaire FrankenPHP fourni par Laravel Octane est souvent livré pour PHP 8.4. Si votre système utilise PHP 8.5 ou si vous avez besoin d’extensions absentes du binaire statique, il faut installer PHP-ZTS (Zend Thread Safety) et FrankenPHP à partir des paquets système. Ce guide décrit la procédure sur Debian/Ubuntu et comment débloquer les erreurs « fantômes » avec --log-level=debug.

Prérequis

• Debian ou Ubuntu
• Laravel Octane avec driver FrankenPHP
• Droits root ou sudo pour installer des paquets

1. FrankenPHP et PHP : binaire statique vs PHP-ZTS

FrankenPHP ne s’appuie pas sur votre installation PHP classique. Il repose sur PHP-ZTS, une variante thread-safe de PHP. Le binaire statique téléchargé par php artisan octane:install est figé (souvent en PHP 8.4) et n’utilise pas les extensions installées via apt pour php8.5 standard. Pour PHP 8.5 ou des extensions spécifiques, il faut passer à une installation dynamique basée sur PHP-ZTS.

2. Ajouter le dépôt PHP 8.5 (Henderkes)

Le dépôt de Marc Henderkes fournit des builds PHP-ZTS pour Debian/Ubuntu. Installation du dépôt pour 8.5 :

curl -fsSL https://files.henderkes.com/install.sh | sudo sh -s 8.5

Pour Fedora/CentOS, des RPM sont disponibles sur rpms.henderkes.com ; le script ci‑dessus cible Debian/Ubuntu.

3. Installer les extensions PHP-ZTS

Les paquets php-* classiques ne sont pas utilisés par FrankenPHP. Il faut les variantes php-zts-* :

sudo apt install php-zts-{bcmath,bz2,gd,gmp,intl,zip,sqlite3,mysql,mbstring}

À adapter selon les besoins de votre app (pdo, xml, curl, etc.). mysql et mbstring sont courants pour Laravel.

4. Installer FrankenPHP

Une fois PHP-ZTS et les extensions en place :

sudo apt install frankenphp

Octane utilisera alors le binaire frankenphp du système, lié à PHP 8.5 ZTS, au lieu du binaire statique téléchargé par Octane.

5. Démarrer Octane

php artisan octane:start

Avec le driver FrankenPHP et le frankenphp système installé, la version PHP effective sera celle de votre stack ZTS (8.5).

6. Dépannage : erreurs « fantômes » et --log-level=debug

Si FrankenPHP plante ou se comporte de façon étrange sans message clair (extensions manquantes, erreurs au démarrage des workers), les logs par défaut peuvent être insuffisants. Pour afficher les erreurs internes des workers dans le terminal :

php artisan octane:start --log-level=debug

Cela permet d’identifier rapidement des extensions manquantes ou des erreurs de démarrage que le niveau de log habituel ne montrerait pas.

Dépannage

Bonnes pratiques

• Ne pas se fier au binaire statique si vous avez besoin d’une version de PHP ou d’extensions précises.
• Installer uniquement les extensions php-zts-* nécessaires pour limiter la surface et les mises à jour.
• Utiliser --log-level=debug en premier recours lors de problèmes de workers Octane/FrankenPHP.

Ressources

• Daniel Petrica – Running PHP 8.5 with Laravel Octane and FrankenPHP
• Henderkes – PHP-ZTS packages / rpms.henderkes.com
• Documentation Laravel Octane
• FrankenPHP

Cet article s’inscrit dans notre série de guides technique et développement web. Pour un serveur ou une application sur-mesure, contact.