PHP extensions and php.ini settings

PHP is only as useful as the extensions it has loaded and the limits it runs with. When an application says "Class 'Imagick' not found" or "The uploaded file exceeds upload_max_filesize", the answer is on the server's Runtimes tab, not in a terminal. SrvYard installs extensions with a switch, applies the most common limits to every PHP version with one button, and lets you edit the PHP configuration files with a safety net.

This article covers the three places to change PHP's behaviour, from the simplest to the most flexible: extensions, global settings and the configuration files themselves.

Before you begin#

• A server in the Ready state with at least one PHP version installed. See Choose and switch PHP versions.
• The permission to manage PHP on the server.
• Only one PHP change runs at a time. If a version is being installed or updated, wait for it to finish; the page tells you when another operation is still running.

1. Switch an extension on or off#

Open Runtimes, find the version in the PHP card, open the menu at the end of its row and choose Extensions.

1. The switch of an extension. Each line shows the name and the package behind it, for example Redis and php8.4-redis. SrvYard offers fourteen: BCMath, Bzip2, GD (images), GMP, ImageMagick, Intl, LDAP, Memcached, MongoDB, OPcache, Redis, SOAP, SQLite3 and Xdebug. Switching one on installs its package, switching it off removes it.
2. Debugging extensions such as Xdebug slow PHP down noticeably. Switch them on to debug and off again afterwards, and never leave Xdebug on a production site.
3. The note at the top. Installing or removing an extension reloads PHP-FPM for this version. Sites on that version keep serving: a reload finishes the requests that are running and starts the new workers with the new extensions.

Extensions apply to one PHP version. If a site runs on 8.3 and you switched Redis on for 8.4, the site does not have it.

1. Also loaded. The long list at the bottom (curl, mbstring, openssl, pdo_mysql, zip and so on) shows what is built into PHP or installed with the base packages. They cannot be switched here, and the count (18 in this example) tells you how many there are.

If an extension is not in either list, you cannot add it from this page. Install it over SSH from the same repository (sudo apt install php8.4-<name>) and press Refresh on the Runtimes tab to pick it up.

2. Change limits for every version#

The Global settings card sits lower on the same tab. It applies to every installed PHP version at once, so a site keeps the same limits when you move it to another version.

1. Max upload size (MB). Sets upload_max_filesize and post_max_size together. Accepts 1 to 4096. A form that uploads a 40 MB video needs a value above 40.
2. Max execution time (seconds). Sets max_execution_time and also the FPM request_terminate_timeout and Nginx's fastcgi_read_timeout, so all three agree and a long request is not cut off by the one you forgot. Accepts 1 to 3600.
3. OPcache for production. Caches compiled code and stops checking files for changes, which makes PHP faster. The price: PHP-FPM must be reloaded after every deploy so that new code is noticed. The generated deploy script ends with srvyard_reload_php for exactly this reason; if you write your own script, keep that line.
4. Apply to all versions. Writes the values, checks the result with PHP-FPM's own test, reloads PHP-FPM and updates Nginx's timeout. If PHP-FPM or Nginx rejects the new settings, SrvYard restores the previous files and tells you which one refused.

3. Edit php.ini and the pool#

For anything else (memory_limit, max_input_vars, display_errors, FPM workers) edit the files directly. Open the version's menu and choose Edit php.ini and pool.

The panel has three tabs:

• FPM php.ini is /etc/php/<version>/fpm/php.ini, the file the web requests use.
• CLI php.ini is /etc/php/<version>/cli/php.ini, the file for the command line, queue workers and scheduled commands.
• Pool (www.conf) is /etc/php/<version>/fpm/pool.d/www.conf, where PHP-FPM's process settings live.

Pick a tab, change the text and press Save and apply. The panel explains the safety net in one sentence: The current file is backed up, the new one is checked, and the backup is restored if PHP rejects it. For the FPM files, PHP-FPM is reloaded once the check passes. An empty file, a file that is too large or one that is not plain text is refused before anything is sent.

A few habits that save trouble:

• Change one thing at a time and test it.
• Prefer the global settings for the limits they cover; use the editor for the rest.
• Remember that FPM and CLI are separate files. A memory_limit that you raise in FPM does not help php artisan on the command line.
• Never put secrets in php.ini.

4. See what SrvYard ran#

Every change in this article is an operation with a log. The Recent operations card at the bottom of the Runtimes tab lists them.

1. Recent operations. What SrvYard last ran for PHP and Node.js on this server. Each operation keeps its output, so when a change fails the line that explains why is on record. On a server without changes the card says Nothing yet.

Troubleshooting#

• "Class 'Imagick' not found" (or another extension error) after switching it on. The site runs on another PHP version than the one you changed. Check the Sites column of the version and the site's PHP version under Settings.
• Uploads still fail at the old limit. Something else in the chain is smaller: the application's own limit, or client_max_body_size in the site's Nginx configuration. The site's generated Nginx file allows 64 MB by default.
• A request still ends after 60 seconds. Another timeout is shorter, for example a proxy or load balancer in front of the server, or the application's own limit. The three timeouts SrvYard sets are always equal.
• "php-fpm… rejected the new settings; its previous configuration was restored". Your value is invalid. Open the failed operation in Recent operations to read PHP's complaint, correct the value and save again.
• Changes in code do not show up after I switched OPcache for production on. That is what it does. Reload PHP-FPM from the version's menu (Reload PHP-FPM), or let your deploy script do it.

Related#

• Choose and switch PHP versions: install the version before you configure it.
• Redis, Memcached and cache services: the services behind the Redis and Memcached extensions.
• Composer and global tools: the other tools that run on PHP.
• Write and test a deploy script: where to reload PHP-FPM after a deploy.