2. Requirements #

This chapter lists what a machine needs before Exponential can be installed on it, and why each item is needed: the PHP version (7.4 to 8.5; 8.0 for Velocity and Layouts), every PHP extension with the place in the code that asks for it, the php.ini settings the setup wizard checks, the database servers and their minimum versions, Composer, a web server, and notes for Red Hat Enterprise Linux 9 and its rebuilds, Debian and Ubuntu, and Plesk. It ends with what the documentation says about memory and disk. Everything here is taken from composer.json, settings/setup.ini, settings/site.ini and kernel/setup/; where a document and the code disagree, the code wins and the chapter says so. Check a machine against this chapter before you download anything: a missing extension found now costs a package install, found half-way through an install it costs a restart of the install.

Contents · Previous: 1. Introduction · Next: 3. Getting the code

2.1 The checklist #

The fastest way to check a machine is to let the setup wizard do it: its System check page runs every critical test and prints, for each failure, the cause and the fix (for permissions the exact chmod and chown commands). The tests are described in 2.4. The kickstarter and exp:install run the same tests in their SystemCheck step and stop there with the same messages, so a command-line install is an equally good check (for the command line PHP).

2.2 PHP #

Versions #

Supported: PHP 8.0 to 8.5. Usable without support: PHP 7.4 (Exponential 6.0.15 and later). "Without support" means: the software is designed to be usable on PHP 7.4, but the project gives no bug-fix or security commitment specific to PHP 7.4, you use it at your own risk, and the features that need PHP 8 are not available there.

composer.json declares:

"php": "^7.4 || ^8.0 || ^8.1 || ^8.2 || ^8.3 || ^8.4 || ^8.5 || ^8.6 || ^8.7 || ^8.8"

so Composer refuses to install on anything older than 7.4. The versions after 8.5 are accepted by the constraint but have not been released or tested. Use the newest PHP your system offers: each version brings speed, and the older ones lose security support first (see PHP's supported versions). PHP 7.4 itself has had no security support from the PHP project since November 2022; run it only where your distribution or host still patches it, and plan the move to PHP 8.

One metapackage per PHP range. The kernel also requires se7enxweb/exponential-php-floor (~1.0.3 || ~1.1.4 || ~1.2.3 || ~1.3.3). Each of its versions belongs to one PHP range and requires the extension releases and the Twig 3 release that run there: 1.0.3 for PHP 7.4 (usable without support, se7enxweb/twig ~3.11.4), 1.1.4 for 8.0 (se7enxweb/twig ~3.19.1, with Exponential Layouts, expsite and the media site theme), 1.2.3 for 8.1 to 8.3 and 1.3.3 for 8.4 and later (twig/twig ^3.27). The earlier versions (1.0.0 to 1.0.2, 1.1.0 to 1.1.2, 1.2.0 to 1.2.2, 1.3.0 to 1.3.2) allowed older extension releases or install no Twig and are left out. The kernel does not require twig/twig itself: upstream Twig up to 3.26 is blocked by security advisories and 3.27 needs PHP 8.1. Composer installs the version that matches the PHP it runs with, so the same composer require se7enxweb/exponential gives a complete installation on every supported PHP, with Composer's security checks left on. Run Composer with the PHP the site will use (see Command line and web PHP).

The GraphQL library is optional. The GraphQL API runs on webonyx/graphql-php 15 (^15.32.3), which composer.json suggests and lists under require-dev, but does not require, and which the metapackage does not install: Exponential Platform Legacy 3.x (ibexa/graphql-php 0.13) and 4.6.x on PHP 7.4 (se7enxweb/graphql-php 14) bring another version for their own GraphQL bundle, and a requirement made them fail to install. The kernel on its own (composer create-project, or composer install in a checkout) installs it; with --no-dev, add it with composer require webonyx/graphql-php:^15.32.3. Without it, or with another version, only the GraphQL API is unavailable and says why (The library).

In 6.0.15 PHP 8.0 is supported again, and PHP 7.4 is usable again, without support. The published releases v6.0.8 to v6.0.14 require PHP 8.1 in their composer.json, and v6.0.7 requires 7.4 or 8.1, so on PHP 7.4 or 8.0 install the 6.0.15 line (dev-main until its tag is published; chapter 3).

On PHP 7.4 and 8.0, autoload.php loads lib/phpcompat.php, which defines the few functions these versions lack (array_is_list() among them), and Composer installs symfony/polyfill-php80 and symfony/polyfill-php81 for the rest (str_contains() and the like); on 8.1 and later these files do nothing. The details are in PHP 8.0 support and Why Exponential supports PHP 7.4. The history of the PHP 8 work since 6.0.0 is in PHP 8 support.

How to check. The first line of php -v names the version:

PHP 8.5.11 (cli) (built: Sep 22 2026 13:32:06) (NTS gcc x86_64)

The setup wizard's PHP check. The critical test phpversion compares the running PHP with settings/setup.ini, [phpversion] MinimumVersion=7.4.0 (the same lower bound as composer.json) and refuses the versions listed in UnstableVersions (6, the PHP version that was never released). Since Composer already enforces 7.4, this test fails in practice only when the web server's PHP is older than the command line PHP that ran Composer, which is exactly the case it is there to catch.

64-bit PHP. composer.json suggests php-64bit: "For support of more than 30 languages, a 64bit php installation on all involved prod/dev machines is required". The reason is that the languages of an object are kept as bits of one integer. The PHP packages of the current Linux distributions are 64-bit builds; on PHP 8.5, php -i | grep "Integer Size" prints PHP Integer Size => 64 bits on such a build.

Command line and web PHP #

Exponential uses PHP twice: the web server's PHP (PHP-FPM, mod_php or Velocity's workers) serves pages, and the command line PHP (php) runs Composer, the installers, the console, the cronjobs and Velocity itself. Both must be of a supported version and have the same extensions. On machines with several PHP versions (Plesk, Remi) the php on the PATH is often not the one the web server uses; call the right binary by its path, for example /opt/plesk/php/8.5/bin/php bin/php/console ....

What goes wrong when they differ: Composer, run with a newer command line PHP, picks package versions the web PHP cannot run, or the command line install succeeds and the browser then shows a white page because the web PHP lacks an extension. Compare php -v and php -m with the PHP information page of the web server before you install.

2.3 PHP extensions #

Three sources decide which extensions are needed: composer.json (require and suggest), and the setup wizard's tests, listed in settings/site.ini, [SetupSettings] CriticalTests (must pass) and OptionalTests (reported only), with their parameters in settings/setup.ini.

Required #

The wizard's messages for a missing extension read, for example, "Missing DOM extension", "Missing xsl extension", "Missing intl extension" or "Missing database handler" ("No supported database handlers were found. Exponential requires a database to store it's data, without one the system will fail."). They come from design/standard/templates/setup/tests/.

For Velocity the engine package adds its own: it requires sockets (TCP options on client connections) and suggests pcntl (graceful shutdown and the worker pool) and openssl (HTTPS). In practice all three are needed for a production Velocity.

Database extensions #

The optional test database_all_extensions reports which of sqlite3, mysqli, pgsql and mongodb are missing; it is only information. Install only the extension of the database you use.

Recommended #

The optional test texttoimage_functions checks imagettftext() and imagettfbbox() (GD with FreeType), which the text-to-image template operator needs. imagemagick_program looks for convert in /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin.

Finding what is missing #

php -m

lists the extensions the command line PHP has. With Velocity installed, the console also compares the machine with the extension set of the Velocity package:

php bin/php/console exp:velocity ext check

prints one line per extension, marked ok or missing, with what each is for, for example:

PHP 8.5 on linux-x86_64: provides the 'lite' set; checked against 'standard'
  ok  sockets          server       TCP options (no-delay, keep-alive) on client connections
  ok  dom              required     XML documents: rich text, packages, feeds, WebDAV
  ok  intl             required     Locale-aware formatting, collation and transliteration

and exp:velocity ext install-hint <extension> ... prints the package install command for your system, for example php bin/php/console exp:velocity ext install-hint intl xsl. (exp:velocity ext list|check|plan|install-hint|build hands over to the engine's qbixctl ext:<action>, so it needs the Velocity package, see chapter 3; as root add --allow-root-user.)

2.4 The setup wizard's system check #

The wizard runs the tests in [SetupSettings] CriticalTests on its System check page and those in OptionalTests on System finetuning. A critical failure stops the wizard until it is fixed (or the test is ignored with its checkbox, which is not recommended: an ignored test usually fails again later as a broken page).

Critical tests #

The directory test runs as the user that runs the check: in the browser the web server's user, on the command line whoever starts the kickstarter. A command-line install by another user can pass the test and still leave files the web server cannot write; chapter 3 shows how to hand them over.

Optional tests #

variables_order (must contain E, so PHP registers environment variables), php_magicquotes, curl_extension, imagegd_extension, imagemagick_program, database_all_extensions, php_register_globals, texttoimage_functions and open_basedir. The last one warns when open_basedir is set: "open_basedir is in use and can give problems running Exponential due to bugs in some PHP versions."

All test functions are in kernel/setup/ezsetuptests.php; the messages are in design/standard/templates/setup/tests/<test>_error.tpl.

2.5 php.ini settings #

A minimal set for a production php.ini (or a PHP-FPM pool's php_admin_value lines):

memory_limit = 256M
max_execution_time = 60
date.timezone = Europe/Berlin
file_uploads = On
upload_max_filesize = 64M
post_max_size = 64M
allow_url_fopen = On
variables_order = "EGPCS"

The values above the minimums are suggestions, not requirements: size them for the largest file your editors upload and the longest import you run through the browser.

The time zone in detail. index.php sets UTC when php.ini has no date.timezone. The test fails only in that case: a php.ini that sets date.timezone, even to UTC, is a decision and passes (eZSetupTestTimeZone()). The site can also set its own time zone in settings/site.ini, [TimeZoneSettings] TimeZone (applied by the kernel on every request), and config.php can call date_default_timezone_set(); the commented example is in config.php-RECOMMENDED. The valid names are listed in the PHP manual's List of Supported Timezones.

After editing php.ini, restart or reload what runs PHP: PHP-FPM, Apache with mod_php, or Velocity (php bin/php/console exp:velocity restart). php --ini shows which files the command line PHP reads; the web PHP may read others (PHP-FPM pools have their own php_admin_value lines). A change that "does not work" is most often a change to the file the other PHP reads.

2.6 Databases #

Supported databases (Exponential 6.0.x), in order of preference: 1. SQLite 3 (the default) · 2. PostgreSQL · 3. MongoDB · 4. MariaDB · 5. Oracle · 6. MySQL. Microsoft SQL Server is known to be possible with additional work at this time. Details: Database support.

The minimum versions the wizard checks are those of eZSetupDatabaseMap() in kernel/setup/ezsetupcommon.php. They are floors, not recommendations: run a version your vendor still supports. The practical minimums come from the drivers; Database support explains each one and lists the versions seen working on the development server and in CI.

• SQLite is the default (settings/setup.ini, [DatabaseSettings] DefaultType=sqlite3) and needs no server: the database is one file under var/storage/sqlite3/. It is a full production database; see the SQLite feature page.
• PostgreSQL needs the pgcrypto extension in the database (its digest function). The wizard tries to create it; when it cannot, it says so and asks for CREATE EXTENSION pgcrypto; by the database owner or a superuser.
• MongoDB and Oracle: see their pages, MongoDB and SQLite and Oracle drivers.
• MariaDB or MySQL: the database must use UTF-8. When the database's character set differs from the one the wizard wants, the wizard stops with "The database [...] cannot be used, the setup wizard wants to create the site in [...] but the database has been created using character set [...]". Create the database with CHARACTER SET utf8mb4 and this cannot happen.
• Microsoft SQL Server has no driver in 6.0.x; what it would take is listed in Database support.

For a database server, create the database and a user that may create tables in it before you install; the installers do not create databases or users. Choosing and tuning a database is the subject of chapter 9.

2.7 Composer #

Exponential installs with Composer 2. Composer downloads the kernel's libraries (the expcomponents, since 6.0.15 Exponential's fork of the Zeta Components), the extensions composer.json requires and, when you ask for it, Velocity. Without Composer, or without running it, vendor/ is missing and the site cannot start.

• Install it as described on getcomposer.org/download and check with composer --version, which prints the Composer version and the PHP it runs with, for example Composer version 2.8.12 2025-09-19 13:41:59 and PHP version 8.5.11 (/usr/bin/php).
• composer.json lists the installer plugin se7enxweb/exponential-legacy-installer under config.allow-plugins. That setting exists since Composer 2.2; an older Composer 2 ignores it. Use a current Composer 2.
• Composer runs with the command line PHP. Its version and extensions are the ones Composer checks the ext-* and php requirements against.
• The development requirements are chosen to fit every supported PHP. composer.json has require-dev "phpunit/phpunit": "^9.6 || ^10.5 || ^11.5 || ^12.0 || ^13.4", and Composer picks the PHPUnit that fits the PHP in use (9.6 on 8.0, 10.5 on 8.1, 11.5 on 8.2, 12 on 8.3, 13.4 on 8.4 and 8.5). This matters because the repository ships no composer.lock, and without a lock file Composer resolves require-dev even with --no-dev. The test suite itself needs PHPUnit 10 or later, so it runs on PHP 8.1 and later. The release tags v6.0.13 and v6.0.14 still ask for PHPUnit 13.0.0, which needs PHP 8.4.1; installing those tags on an older PHP is shown in chapter 3.

composer install runs the script legacy-scripts afterwards (post-install-cmd and post-update-cmd in composer.json), which is php bin/php/ezpgenerateautoloads.php: the class maps are generated for you.

2.8 Web server #

None is needed during a kickstarter or console install; the setup wizard needs one, because it runs in the browser. Setting each one up is the subject of chapter 8 and the Deploying guide.

2.9 Operating system notes #

Exponential runs wherever PHP runs; the installation is plain files. The notes below cover the systems the documentation and the code name. The package names are the ones Velocity's extension manifest (vendor/se7enxweb/exponential-velocity/build/extensions.json) gives, which is what exp:velocity ext install-hint prints.

Red Hat Enterprise Linux 9, AlmaLinux 9, Rocky Linux 9 #

• The stock PHP of the AppStream repository is 8.0, which runs Exponential under Apache, PHP-FPM or Velocity. The command from PHP 8.0 support:

  dnf install php php-fpm php-mysqlnd php-gd php-intl php-mbstring php-xml php-pdo php-opcache

  php-xml brings dom, simplexml, xsl and libxml; php-pdo brings sqlite3; php-common (a dependency) brings iconv, zlib, session and openssl; php-process brings pcntl; php-pgsql adds PostgreSQL.

• Velocity needs no newer stream: it runs on the stock 8.0 from its release 0.0.4.54 (see PHP 8.0 and Red Hat Enterprise Linux below). For a newer PHP, switch to another AppStream module stream: dnf module list php, then dnf module reset php, dnf module enable php:8.3 and dnf distro-sync. The streams php:8.1, php:8.2 and php:8.3 run both Exponential and Velocity.

• The Remi repository (php:remi-8.x module streams, or the parallel php<XY> packages under /opt/remi) provides every version from 8.0 to 8.5. PECL extensions (php-pecl-redis, php-pecl-apcu, php-pecl-mongodb) and oci8 come from EPEL, Remi or the vendor.

• The service of the stock PHP-FPM is php-fpm; a Remi parallel install is php<XY>-php-fpm.

PHP 8.0 and Red Hat Enterprise Linux #

From release 0.0.4.54 (20 October 2026) Exponential Velocity runs on PHP 8.0 to 8.5: the engine's composer.json requires "php": ">=8.0" (it was >=8.1), and nothing extra is needed on 8.0, no polyfill package and no extension. Exponential's composer.json requires the engine at ~0.0.4.57, so composer install on PHP 8.0 installs it too.

• RHEL 9 and its rebuilds: the default AppStream PHP 8.0 runs Velocity. The el9 rpm (exponential-velocity-<release>-1.el9.noarch.rpm) depends on php-cli >= 8.0 and installs without enabling a module stream; a newer stream still works. Composer works the same way.
• RHEL 8: the default PHP there is 7.2. Enable the 8.0 stream (dnf module enable php:8.0) and use the phar or Composer; there is no el8 rpm.

What differs on PHP 8.0, and only this: AVIF image output needs PHP 8.1 (the image negotiation stops at WebP); the dashboard's per-request memory peak needs PHP 8.2 (the column is empty); $_FILES has no full_path, as in PHP 8.0 itself; and a class declared with eval() that has static properties makes its worker get replaced after that request (correct, and it costs one fork). The engine handles the rest itself, and its zygote runs on 8.0. Extensions, systemd, SELinux and how to verify the installation: the engine's PHP 8.0 and Red Hat Enterprise Linux page and its requirements.

Debian and Ubuntu #

• The packages are named after the PHP version: php<version>-<extension>, for example php8.3-intl. The extensions Exponential needs are in php8.3-xml (dom, simplexml, xsl, libxml), php8.3-mbstring, php8.3-intl, php8.3-common (iconv and the other common extensions), php8.3-sqlite3, php8.3-mysql (mysqli), php8.3-pgsql, php8.3-gd, php8.3-curl and php8.3-opcache; pcntl is in php8.3-cli.
• Replace 8.3 with the version your release ships.
• The PHP-FPM service is php<version>-fpm, with its pools in /etc/php/<version>/fpm/pool.d/.
• The Velocity package is also published as a .deb; see Velocity packages and binaries.

Plesk #

• Plesk installs each PHP version under /opt/plesk/php/<version>/ (for example /opt/plesk/php/8.5/bin/php) next to the system's PHP. A domain uses the version chosen in its hosting settings; the command line php is the system's. Run Composer and the console with the domain's PHP.
• The bundled extensions ship with Plesk's PHP and are switched on under Tools & Settings > PHP Settings; PECL extensions are installed with /opt/plesk/php/<version>/bin/pecl install <extension>.
• Each domain has its own PHP-FPM pool in /opt/plesk/php/<version>/etc/php-fpm.d/<domain>.conf, run by the service plesk-php<XY>-fpm (for example plesk-php85-fpm), not by php-fpm. After a PHP change, reload that one. exp:velocity deploy finds it by itself (settings/velocity.ini, [DeploySettings] PhpFpmService=auto looks in /opt/plesk/php/*/etc/php-fpm.d, /etc/php-fpm.d, /etc/php/*/fpm/pool.d and /etc/opt/remi/php*/php-fpm.d).

Other systems #

The Velocity manifest also knows Alpine (apk), FreeBSD (pkg), macOS (Homebrew) and Windows. The kernel's setup tests have Windows paths for ImageMagick (convertim.exe, convert.exe), but this book is written for Linux.

Exponential runs on almost any operating system with PHP 8.0 or later (PHP 7.4 usable without support) and a web server. Operating system support sorts them into tiers (tested here, known to work, expected to work, not possible today), from the Linux distributions, the BSDs, macOS and Windows to IBM i, Haiku and the 8-bit machines, and lists the web servers and PHP SAPIs.

2.10 Memory, CPU and disk #

The documentation gives few hard numbers, and this book does not invent others. What it does state:

Disk use grows with var/storage (uploaded files and image variations), var/cache and var/log; the database grows with the content. Measure a running site rather than guessing: the benchmark command times pages, and Velocity's control panel shows memory use. Read Velocity's memory as the control panel shows it, the proportional set size (PSS) of the parent and its workers: the resident set size of each forked worker counts the memory they share again and again, and adds up to far more than the machine really uses.

Environment variables. Exponential reads a few environment variables, listed in Environment variables. One of them, EXP_DEMO_MODE=1, marks an installation as a public demo (Demo mode); a production server must not set it for any process of a real site.

References #

In this repository:

• Installation overview, section 2.
• Database support and Operating system support.
• PHP 8.0 support and PHP 8 support.
• SQLite database support, SQLite 3 driver, MongoDB, SQLite and Oracle drivers, Database drivers, September 2026.
• Velocity engines, Velocity web server, Velocity packages and binaries.
• Deploying.
• Quality checks and Continuous integration: how PHP 8.0 is tested.
• Code: composer.json, settings/setup.ini, settings/site.ini ([SetupSettings]), kernel/setup/ezsetuptests.php, kernel/setup/ezsetupcommon.php, design/standard/templates/setup/tests/, vendor/se7enxweb/exponential-velocity/composer.json.

External:

• PHP: supported versions, installation and configuration, php.ini directives, file uploads, List of Supported Timezones, PHP 8.0 migration.
• PHP extensions: DOM, XSL, intl, mbstring, SQLite3, mysqli, PostgreSQL, GD, MongoDB, OCI8, Sockets, PCNTL.
• Composer: download, allow-plugins.
• PHPUnit: supported versions.
• Velocity on Packagist: se7enxweb/exponential-velocity.
• Remi repository: rpms.remirepo.net.

Contents · Previous: 1. Introduction · Next: 3. Getting the code