Preparing PHP

PHP Installation

Refer to your OS distribution's documentation for instructions for establishing a base PHP installation. It may be possible to choose among several versions of PHP. Refer to :doc:`./system_requirements` to see which versions of PHP are supported by this release of Nextcloud Server. After completing a base PHP installation, follow the below guidance to configure your new PHP installation for your new Nextcloud Server deployment.

Required PHP Modules

The following PHP modules must be installed and enabled for Nextcloud Server to function:

• ctype (included with PHP)

• curl

• DOM

• fileinfo (included with PHP)

• filter (only on Mageia and FreeBSD)

• GD

• xml (provides SimpleXML, XMLReader and XMLWriter; requires Linux package libxml2 version >= 2.7.0)

• mbstring

• OpenSSL (included with PHP)

• posix

• session (included with PHP)

• zip

• zlib

The ctype, fileinfo, and OpenSSL modules are generally included and enabled in PHP by default. Often some of the other required modules are automatically installed by OS distribution package managers.

How to check if a module is enabled:

• Run php -m | grep -i <module_name>. If you see output, the module is active.

Required PHP Database Connectors

Install the PHP connector module for the database you plan to use (choose one):

• pdo_sqlite (>= 3, usually not recommended for performance reasons)

• pdo_mysql (MySQL/MariaDB)

• pdo_pgsql (PostgreSQL)

Recommended General PHP Modules

These modules are not required, but are highly recommended to improve functionality or security:

• intl: Fixes sorting of non-ASCII characters and improves language translation performance.

• sodium: Provides Argon2 password hashing (needed if using PHP < 8.4 and PHP was built without libargon2). Starting with PHP 8.0, sodium is usually enabled by default. In PHP 8.4, sodium is typically bundled.

  bcrypt will be used if Argon2 is unavailable, but if passwords were previously hashed with Argon2 (such as when migrating an existing Nextcloud Server installation to a new server environment) and this module is missing, accounts will not be able to log-in).

• sysvsem: Enables System V semaphores used by Nextcloud to coordinate preview generation across PHP processes. Recommended; if missing, previews still work but may be less reliable under heavy load.

Recommended PHP Caching Modules

Memory caching is not required so these modules are not required, but are highly recommended for optimal performance and reliability. Choose and install your preferred combination of memory caching modules:

• APCu (>= 4.0.6)

• redis / phpredis (>= 2.2.6, required for Transactional File Locking)

• memcached (an older alternative to redis that is not recommended for new installations)

See :doc:`../configuration_server/caching_configuration` for configuration details.

Recommended PHP CLI Modules

For command-line processing (optional):

• pcntl: Allows command interruption (e.g., via ctrl-c).

  Ensure pcntl_signal and pcntl_signal_dispatch are not disabled in your php.ini by the disable_functions option.

For command-line updater (optional):

• phar: Required to run the updater with:

  sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar

PHP Modules for Media Management

Image meta data and orientation (optional):

• exif: Image meta data loading and rotation

Preview Generation (optional):

• imagick (for image previews)

• avconv or ffmpeg (for video previews)

• OpenOffice or LibreOffice (for document previews)

See :doc:`../configuration_files/previews_configuration` for additional preview generation context.

PHP Modules for Specific Applications

Some optional Nextcloud apps/functionality require additional modules. Install as needed:

• ldap: LDAP integration

• smbclient: SMB/CIFS integration (see :doc:`../configuration_files/external_storage/smb`)

• ftp: FTP storage or external user authentication

• imap: External user authentication

Recommended/Optional:

• gmp: SFTP storage

PHP ini Settings

Adjust the following settings in your php.ini as needed for Nextcloud:

• disable_functions: Avoid disabling functions unless necessary.

• max_execution_time: See :doc:`../configuration_files/big_file_upload_configuration`

• memory_limit: Should be at least 512MB. See also :doc:`../configuration_files/big_file_upload_configuration`

• opcache.enable and related settings: See :doc:`../configuration_server/caching_configuration` and :doc:`server_tuning`

• open_basedir: See :doc:`harden_server`

• upload_tmp_dir: See :doc:`../configuration_files/big_file_upload_configuration`

Notes on PHP ini Configuration

• Multiple php.ini files:

  • You may need to configure settings in more than one php.ini file (e.g., for web server and CLI).

    • Web server:

      /etc/php/<version>/apache2/php.ini or /etc/php/<version>/fpm/php.ini

    • CLI (used by Nextcloud CRON jobs):

      /etc/php/<version>/cli/php.ini

• Find which php.ini is active for each SAPI:

  • Use php --ini for CLI, or check phpinfo() in a web page.

• Search for a parameter:

  • Run grep -r <parameter_name> /etc/php (e.g., grep -r date.timezone /etc/php)

• Replace `<version>` with your actual PHP version (e.g., 8.1, 8.2, etc.).

PHP Module Quick Reference Table

*The filter module is required only on Mageia and FreeBSD.

Further Resources

• For more details on each module, consult the official PHP documentation.

• Refer to your OS distribution's documentation for the specifics of installing PHP modules in your environment.

• The words extension and module are interchangeable within PHP. We use the word modules in our documentation.

• Always restart your web server and PHP-FPM after making changes to an php.ini file or installed modules.