Skip to main content

PHP-FPM

What is PHP-FPM?​

PHP-FPM (FastCGI Process Manager) is the process manager that runs your PHP application code and talks FastCGI to a web server. In Laradock, php-fpm is the container that actually executes your app, nginx/apache proxy requests to it rather than running PHP themselves.

This page covers the container itself: how it's started, what it reads from .env, how other services depend on it, and how to switch PHP versions and install extensions and debuggers.

Start PHP-FPM​

./laradock start php-fpm

Web servers depend on php-fpm to serve dynamic requests, so bring it up alongside one:

./laradock start nginx php-fpm

php-fpm itself depends_on: workspace in compose.yml, both containers build from the same PHP version and share build logic.

Stop PHP-FPM​

./laradock stop php-fpm

To delete the container entirely (your app code, which lives under APP_CODE_PATH_HOST and isn't owned by this container, is untouched):

./laradock remove php-fpm

Configuration​

The PHP version is controlled by the shared PHP_VERSION variable in the root .env (default 8.4), not by a php-fpm-specific variable, it's passed into the build as LARADOCK_PHP_VERSION. Everything else lives in php-fpm/defaults.env as PHP_FPM_INSTALL_* build-time toggles. A few default to true:

VariableDefaultWhat it does
PHP_FPM_INSTALL_MYSQLItrueMySQLi extension.
PHP_FPM_INSTALL_INTLtrueInternationalization extension.
PHP_FPM_INSTALL_IMAGEMAGICKtrueImageMagick (Imagick) extension.
PHP_FPM_INSTALL_OPCACHEtrueZend OPcache.
PHP_FPM_INSTALL_IMAGE_OPTIMIZERStruejpegoptim, optipng, pngquant, gifsicle.
PHP_FPM_INSTALL_PHPREDIStruePHP Redis extension.
PHP_FPM_INSTALL_DNSUTILStruedig/nslookup and friends.

Everything else (Xdebug, pcov, phpdbg, xhprof, BCMath, PostgreSQL, MongoDB, AMQP, LDAP, SOAP, XSL, SSH2, Swoole, Phalcon, OCI8, MSSQL, ionCube, APCu, YAML, rdkafka, New Relic, and dozens more) defaults to false and follows the same PHP_FPM_INSTALL_<THING>=true + rebuild pattern:

PHP_FPM_INSTALL_XDEBUG=true
PHP_FPM_XDEBUG_PORT=9003
./laradock rebuild php-fpm
./laradock start php-fpm

A few other notable variables: PHP_FPM_PUID/PHP_FPM_PGID (default 1000/1000, match the www-data user's UID/GID to your host user), PHP_FPM_DEFAULT_LOCALE (default POSIX), and PHP_FPM_BASE_IMAGE_TAG_PREFIX (default latest, the laradock/php-fpm base image tag prefix).

Change the PHP-FPM version​

By default the latest stable PHP version runs. PHP-FPM serves your application code.

  1. In .env, set PHP_VERSION to the version you want (any from 5.6 to 8.5): 
    PHP_VERSION=8.1
  2. Rebuild the image:
./laradock rebuild php-fpm

For details on the underlying base image, see the official PHP Docker images.

Check the installed PHP version and extensions​

Open a terminal inside the container to see what's actually loaded, useful after a rebuild or when an extension doesn't seem to be working:

./laradock enter php-fpm
php -v
php -m
php --ini

php -m lists every compiled-in extension, php --ini shows which .ini files PHP actually loaded (useful for confirming laravel.ini and any extension .ini files are in effect).

Tune PHP settings (memory limit, upload size, timeouts)​

Laradock ships two layers of PHP config for php-fpm, and which one to edit depends on whether you want a quick restart to pick it up or need a full rebuild:

  • php-fpm/php{PHP_VERSION}.ini (for example php-fpm/php8.4.ini) is bind-mounted straight into the container as the main php.ini. Edit it and restart, no rebuild needed.
  • php-fpm/laravel.ini is baked into the image at build time (memory_limit, upload_max_filesize, post_max_size, max_execution_time, and a few others tuned for a typical Laravel app). Edit it and you need a rebuild for the change to apply.

To bump the upload size or memory limit, edit whichever file matches, then apply it:

./laradock restart php-fpm

...or, if you edited laravel.ini instead:

./laradock rebuild php-fpm

Process manager limits (how many PHP processes can run at once) live in php-fpm/xlaravel.pool.conf: pm.max_children, pm.start_servers, pm.min_spare_servers, pm.max_spare_servers. This file is baked into the image, so changes here need a rebuild too, same command as above.

OPcache is enabled by default (PHP_FPM_INSTALL_OPCACHE=true, configured in php-fpm/opcache.ini) with opcache.validate_timestamps=1, so PHP-FPM already detects changed files on its own, you don't normally need to clear it manually after deploying new code. If you ever do want to force a clean slate (compiled bytecode is per-process and lives in memory), restarting the container clears it since every worker process restarts fresh.

Install PHP extensions​

PHP extensions are toggled per container. Each PHP container lists a flag for every extension in its defaults.env: php-fpm/defaults.env, workspace/defaults.env, and php-worker/defaults.env.

  1. Find the extension's flag in the relevant container's defaults.env, then set it to true in your .env (for example PHP_FPM_INSTALL_GMP=true).
  2. Rebuild that container with --no-cache:
./laradock rebuild --no-cache {container-name}

The sections below cover the debuggers and the individual extensions Laradock ships with.

Install Xdebug​

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_XDEBUG
    • PHP_FPM_INSTALL_XDEBUG
  2. Rebuild:
./laradock rebuild workspace php-fpm

To configure Xdebug with your IDE, see this Laravel + Laradock + PhpStorm guide.

Start or stop Xdebug​

Once installed, Xdebug runs on startup by default. Control it in the php-fpm container by running these from the Laradock root:

  • Stop it starting by default: ./php-fpm/xdebug stop
  • Start it: ./php-fpm/xdebug start
  • Check status: ./php-fpm/xdebug status

If ./php-fpm/xdebug reports Permission Denied, give it execute access with chmod.

Install pcov​

A fast code-coverage driver for PHP 7.1+.

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_PCOV
    • PHP_FPM_INSTALL_PCOV
  2. Rebuild:
./laradock rebuild workspace php-fpm

For tuning tips, see the pcov README.

Install phpdbg​

The interactive PHP debugger.

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_PHPDBG
    • PHP_FPM_INSTALL_PHPDBG
  2. Rebuild:
./laradock rebuild workspace php-fpm

Install ionCube Loader​

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_IONCUBE
    • PHP_FPM_INSTALL_IONCUBE
  2. Rebuild:
./laradock rebuild workspace php-fpm

The latest loaders are always downloaded from ionCube.

Install the Aerospike extension​

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_AEROSPIKE
    • PHP_FPM_INSTALL_AEROSPIKE
  2. Rebuild:
./laradock rebuild workspace php-fpm

Install the Calendar extension​

  1. In .env, set PHP_FPM_INSTALL_CALENDAR to true.
  2. Rebuild:
./laradock rebuild php-fpm

Install libfaketime​

Libfaketime lets you control the date and time the OS reports, set via the PHP_FPM_FAKETIME variable. For example, PHP_FPM_FAKETIME=-1d moves the clock back one day. See libfaketime for the syntax.

  1. In .env, set PHP_FPM_INSTALL_FAKETIME to true.
  2. Set PHP_FPM_FAKETIME to your desired offset.
  3. Rebuild:
./laradock rebuild php-fpm

Install the YAML extension​

Parse and emit YAML from PHP. See the PHP YAML reference.

  1. In .env, set PHP_FPM_INSTALL_YAML to true.
  2. Rebuild:
./laradock rebuild php-fpm

Install the rdkafka extension​

  1. In .env, set PHP_FPM_INSTALL_RDKAFKA to true.
  2. Rebuild:
./laradock rebuild php-fpm

Composer installs that require Kafka run from the Workspace container instead, see Install the rdkafka extension on the Workspace guide.

Install the Decimal extension​

The Decimal extension adds correctly-rounded, arbitrary-precision decimal arithmetic, useful for money, measurements, and anything where float rounding is unacceptable.

  1. In .env, set both flags to true:
    • WORKSPACE_INSTALL_PHPDECIMAL
    • PHP_FPM_INSTALL_PHPDECIMAL
  2. Rebuild:
./laradock rebuild workspace php-fpm

Common issues​

  • Enabled an extension but it's not loaded. PHP_FPM_INSTALL_* flags only take effect on build: ./laradock rebuild php-fpm then ./laradock start php-fpm.
  • 502 Bad Gateway from your web server. Confirm php-fpm is actually running (docker compose ps php-fpm) and that the web server's upstream config points at the right container/port (php-fpm:9000 by default, container-internal, not published to the host).
  • Xdebug and Blackfire both enabled, neither works. They can't coexist in the same PHP process, the build skips the Blackfire probe when PHP_FPM_INSTALL_XDEBUG=true.
  • File permission mismatches on Linux. Set PHP_FPM_PUID/PHP_FPM_PGID to your host user's id -u/id -g, then rebuild.
  • "PHP Fatal error: Allowed memory size exhausted" or uploads silently failing. Bump memory_limit/upload_max_filesize/post_max_size, see Tune PHP settings above.

Need the container you actually work inside (Composer, Artisan, Git)? See the Workspace guide. New to Laradock? Start at Getting Started.