# Configure PHP on TurboStack

Each application chooses its own PHP version and, optionally, its PHP-FPM and
OPcache tuning.

![The PHP panel under Configure application > Technologies, enabled, with the Select PHP Version field and Advanced Settings expanded to show the PHP-FPM worker fields, the tmp dir option and Enhance Opcache|1000](../../assets/screenshots/technologies/php.png)

## Where to configure it

PHP is configured per application:

1. Open the application.
2. Go to **Configure application > Technologies > PHP**.
3. Select the PHP version (and adjust advanced settings if needed).

Installed versions and the host default come from the host-level `php_versions`
and `php_main_version` settings.

## YAML configuration

### Required

| Key | Meaning |
|---|---|
| `php_version` | PHP version for this application/vhost, e.g. `"8.4"`. |

### Optional

A PHP-FPM worker is one PHP process that handles one request at a time, so the number of workers
sets how many PHP requests the application can serve at once.

| Key | Meaning |
|---|---|
| `php_fpm_pm_start_servers` | Number of PHP-FPM worker processes started initially. |
| `php_fpm_pm_min_spare_servers` | Minimum number of idle PHP-FPM workers kept ready. |
| `php_fpm_pm_max_spare_servers` | Maximum number of idle PHP-FPM workers kept ready. |
| `php_fpm_pm_max_children` | The ceiling on workers this application may run at once. Inherited from the host unless you set it here. |
| `php_fpm_pm_max_requests` | How many requests a worker handles before it is restarted. Inherited from the host (`500`) unless you set it here. |
| `php_user_tmp_dir` | Gives the application its own temporary folder instead of the shared one. Off by default. |
| `php_enhance` | Enable OPcache performance enhancements for the site. |
| `php_opcache_preload_script` | Path to a script preloaded into OPcache at startup. |
| `php_ioncube_enabled` | Enable the ionCube loader (for ionCube-encoded apps). |
| `php_versions` | Host-level: PHP versions installed on the host. |
| `php_main_version` | Host-level: default PHP version for the host. |

```yaml
# Per-application
php_version: "8.4"

# Optional PHP-FPM tuning
php_fpm_pm_start_servers: 5
php_fpm_pm_min_spare_servers: 3
php_fpm_pm_max_spare_servers: 6
# php_fpm_pm_max_children: 40      # ceiling on concurrent workers
# php_fpm_pm_max_requests: 500     # restart a worker after this many requests
# php_user_tmp_dir: true           # a private tmp folder for this application

# Optional OPcache + ionCube
php_enhance: true
php_opcache_preload_script: "/var/www/prod/preload.php"
php_ioncube_enabled: false

# Host-level
php_versions:
  - "8.3"
  - "8.4"
php_main_version: "8.4"
```

> [!NOTE]
> Each application runs in its own PHP-FPM pool, so `php_version` and the PHP-FPM tuning
> keys apply independently per site. Set `php_versions` at the host before a
> application can select that version.

### Worker ceiling and recycling

`php_fpm_pm_max_children` is the hard limit on how many requests this application can process at
the same time. Every worker holds its own memory, so the ceiling multiplied by the memory a request
uses is the worst case for this application. Set it too high and a traffic peak pushes the host out
of memory; set it too low and requests queue and time out. See
[Out of memory](../../troubleshooting/out-of-memory.md) and
[Performance tuning](../../concepts/performance-tuning.md).

`php_fpm_pm_max_requests` restarts a worker after that many requests. Restarting reclaims whatever
the process leaked, which keeps a slowly growing application stable without a scheduled restart.

Both are inherited from the host when you leave them out, so set them per application only when
one site needs to differ from the rest.

### A private temporary folder

With `php_user_tmp_dir: true` the application gets its own `tmp` folder under its home directory,
owned by its own user, and PHP's `sys_temp_dir` points at it. Without it, applications share the
system temporary folder. Turn it on when several applications run on one host and you do not want
uploads, sessions or generated files landing in a place another application can read.

## Common tasks

- [Switch PHP version](switch-php-version.md)
- [Override PHP settings](override-php-settings.md)
- [Flush the OPcache](flush-opcache.md)

## Related

- [What is PHP?](what-is.md)
- [Applications: Technologies](../../platform/hosts/applications/index.md)
- [Applications overview](../../applications/index.md)
- [TurboStack CLI](../../api/cli.md) - clear OPcache (`tscli opcache clear`) and manage Blackfire