Skip to content

Commit 8270062

Browse files
susnuxsusnux
authored
Merge pull request #13573 from nextcloud/jtr/admin-install-php-refactor
refactor(admin): Improve the PHP Modules & Configuration chapter
2 parents 49cde1d + 4f59e8b commit 8270062

2 files changed

Lines changed: 226 additions & 111 deletions

File tree

‎admin_manual/installation/php_configuration.rst‎

Lines changed: 225 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,129 +1,244 @@
1-
===========================
2-
PHP Modules & Configuration
3-
===========================
4-
5-
PHP Modules
6-
-----------
7-
8-
This
9-
section lists all required and optional PHP modules. Consult the `PHP manual
10-
<https://php.net/manual/en/extensions.php>`_ for more information on modules.
11-
You can
12-
check the presence of a module by typing ``php -m | grep -i <module_name>``.
13-
If you get a result, the module is present.
14-
15-
Required:
16-
17-
* PHP (see :doc:`./system_requirements` for a list of supported versions)
18-
* PHP module ctype
19-
* PHP module curl
20-
* PHP module dom
21-
* PHP module fileinfo (included with PHP)
22-
* PHP module filter (only on Mageia and FreeBSD)
23-
* PHP module GD
24-
* PHP module hash (only on FreeBSD)
25-
* PHP module JSON (included with PHP >= 8.0)
26-
* PHP module libxml (Linux package libxml2 must be >=2.7.0)
27-
* PHP module mbstring
28-
* PHP module openssl (included with PHP >= 8.0)
29-
* PHP module posix
30-
* PHP module session
31-
* PHP module SimpleXML
32-
* PHP module XMLReader
33-
* PHP module XMLWriter
34-
* PHP module zip
35-
* PHP module zlib
36-
37-
Database connectors (pick the one for your database):
38-
39-
* PHP module pdo_sqlite (>= 3, usually not recommended for performance reasons)
40-
* PHP module pdo_mysql (MySQL/MariaDB)
41-
* PHP module pdo_pgsql (PostgreSQL)
42-
43-
*Recommended* packages:
44-
45-
* PHP module intl (increases language translation performance and fixes sorting
46-
of non-ASCII characters)
47-
* PHP module sodium (for Argon2 for password hashing when PHP < 8.4 is used and PHP was built without libargon2. bcrypt is used as fallback, but if passwords were hashed with Argon2 already and the module is missing, your users can't log in.)
48-
49-
Required for specific apps:
50-
51-
* PHP module ldap (for LDAP integration)
52-
* PHP module smbclient (SMB/CIFS integration, see
53-
:doc:`../configuration_files/external_storage/smb`)
54-
* PHP module ftp (for FTP storage / external user authentication)
55-
* PHP module imap (for external user authentication)
56-
57-
Recommended for specific apps (*optional*):
58-
59-
* PHP module gmp (for SFTP storage)
60-
* PHP module exif (for image rotation in pictures app)
61-
62-
For enhanced server performance (*optional*) select one or more of the following
63-
caches:
64-
65-
* PHP module apcu (>= 4.0.6)
66-
* PHP module memcached
67-
* PHP module redis (>= 2.2.6, required for Transactional File Locking)
68-
69-
See :doc:`../configuration_server/caching_configuration` to learn how to select
70-
and configure a cache.
71-
72-
For preview generation (*optional*):
73-
74-
* PHP module imagick
75-
* avconv or ffmpeg
76-
* OpenOffice or LibreOffice
1+
=============
2+
Preparing PHP
3+
=============
4+
5+
Before installing Nextcloud Server, ensure your PHP environment is properly configured. This includes installing
6+
the correct PHP version, enabling required PHP modules, and adjusting important `php.ini` settings. This guide
7+
explains which PHP modules are necessary, which are recommended for optimal performance and compatibility, and
8+
how to configure your PHP environment for both web server and command-line usage.
9+
10+
.. note::
11+
You can safely ignore this chapter if you plan to use a turnkey Nextcloud Server installation method (such as
12+
AIO, Snap, NCP, or Community Docker). Those installation methods provide PHP environments that are already
13+
pre-configured for use with Nextcloud Server. For guidance regarding customizing PHP in those environments,
14+
refer to the documentation provided specifically for or by those install methods.
15+
16+
.. contents::
17+
:local:
18+
:depth: 2
19+
20+
----------------
21+
PHP Installation
22+
----------------
23+
24+
Refer to your OS distribution's documentation for instructions for establishing a base PHP installation. It may
25+
be possible to choose among several versions of PHP. Refer to :doc:`./system_requirements` to see which versions
26+
of PHP are supported by this release of Nextcloud Server. After completing a base PHP installation,
27+
follow the below guidance to configure your new PHP installation for your new Nextcloud Server deployment.
28+
29+
--------------------
30+
Required PHP Modules
31+
--------------------
32+
33+
The following PHP modules **must** be installed and enabled for Nextcloud Server to function:
34+
35+
- `ctype` (included with PHP)
36+
- `curl`
37+
- `DOM`
38+
- `fileinfo` (included with PHP)
39+
- `filter` (only on Mageia and FreeBSD)
40+
- `GD`
41+
- `hash` (only on FreeBSD)
42+
- `JSON` (included with PHP)
43+
- `libxml` (requires Linux package `libxml2` version >= 2.7.0)
44+
- `mbstring`
45+
- `OpenSSL` (included with PHP)
46+
- `posix`
47+
- `session` (included with PHP)
48+
- `SimpleXML`
49+
- `XMLReader`
50+
- `XMLWriter`
51+
- `zip`
52+
- `zlib`
53+
54+
The `ctype`, `fileinfo`, `JSON` and `OpenSSL` modules are generally included and enabled in PHP by default. Often
55+
some of the other required modules are automatically installed by OS distribution package managers.
56+
57+
**How to check if a module is enabled:**
58+
59+
- Run ``php -m | grep -i <module_name>``. If you see output, the module is active.
7760

7861
.. note::
79-
If the preview generation of PDF files fails with a "not authorized" error message, you must adjust the imagick policy file.
80-
See https://cromwell-intl.com/open-source/pdf-not-authorized.html
62+
The `filter` and `hash` modules are required only on Mageia and FreeBSD.
8163

82-
For command line processing (*optional*):
64+
--------------------------------
65+
Required PHP Database Connectors
66+
--------------------------------
8367

84-
* PHP module pcntl (enables command interruption by pressing ``ctrl-c``)
68+
Install the PHP connector module for the database you plan to use (choose one):
8569

86-
.. note::
87-
You also need to ensure that ``pcntl_signal`` and ``pcntl_signal_dispatch`` are not disabled
88-
in your php.ini by the ``disable_functions`` option.
70+
- `pdo_sqlite` (>= 3, usually not recommended for performance reasons)
71+
- `pdo_mysql` (MySQL/MariaDB)
72+
- `pdo_pgsql` (PostgreSQL)
8973

90-
For command line updater (*optional*):
74+
-------------------------------
75+
Recommended General PHP Modules
76+
-------------------------------
9177

92-
* PHP module phar (upgrades Nextcloud by running ``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar``)
78+
These modules are not required, but are highly recommended to improve functionality or security:
9379

94-
ini values
95-
----------
80+
- `intl`: Fixes sorting of non-ASCII characters and improves language translation performance.
81+
- `sodium`: Provides Argon2 password hashing (needed if using PHP < 8.4 and PHP was built without `libargon2`).
9682

97-
The following ini settings should be adapted if needed for Nextcloud:
83+
bcrypt will be used if Argon2 is unavailable, but if passwords were previously hashed with Argon2
84+
(such as when migrating an existing Nextcloud Server installation to a new server environment) and this
85+
module is missing, accounts will not be able to log-in).
9886

99-
* ``disable_functions``: avoid disabling functions unless you know exactly what you are doing
100-
* ``max_execution_time``: see :doc:`../configuration_files/big_file_upload_configuration`
101-
* ``memory_limit``: should be at least 512MB. See also :doc:`../configuration_files/big_file_upload_configuration`
102-
* ``opcache.enable`` and friends: See :doc:`../configuration_server/caching_configuration` and :doc:`server_tuning`
103-
* ``open_basedir``: see :doc:`harden_server`
104-
* ``upload_tmp_dir``: see :doc:`../configuration_files/big_file_upload_configuration`
87+
-------------------------------
88+
Recommended PHP Caching Modules
89+
-------------------------------
10590

106-
.. _php_ini_tips_label:
91+
Memory caching is not required so these modules are not required, but are highly recommended for optimal
92+
performance and reliability. Choose and install your preferred combination of memory caching modules:
10793

108-
php.ini configuration notes
94+
- `APCu` (>= 4.0.6)
95+
- `redis` / `phpredis` (>= 2.2.6, required for Transactional File Locking)
96+
- `memcached` (an older alternative to `redis` that is not recommended for new installations)
97+
98+
.. note::
99+
Memory caching is highly recommended for optimal performance. In most cases, a combination of `APCu` and
100+
`redis` are the best choice for new installations.
101+
102+
See :doc:`../configuration_server/caching_configuration` for configuration details.
103+
104+
---------------------------
105+
Recommended PHP CLI Modules
109106
---------------------------
110107

111-
Keep in mind that changes to ``php.ini`` may have to be configured on more than one
112-
ini file. This can be the case, for example, for the ``date.timezone`` setting.
113-
You can search for a parameter with the following command: ``grep -r date.timezone /etc/php``.
108+
**For command-line processing** (optional):
114109

115-
**php.ini - used by the Web server:**
116-
::
110+
- `pcntl`: Allows command interruption (e.g., via ``ctrl-c``).
117111

118-
/etc/php/8.3/apache2/php.ini
119-
or
120-
/etc/php/8.3/fpm/php.ini
121-
or ...
112+
Ensure ``pcntl_signal`` and ``pcntl_signal_dispatch`` are *not* disabled in your `php.ini` by the
113+
``disable_functions`` option.
122114

123-
**php.ini - used by the php-cli and so by Nextcloud CRON jobs:**
124-
::
115+
**For command-line updater** (optional):
125116

126-
/etc/php/8.3/cli/php.ini
117+
- `phar`: Required to run the updater with:
127118

128-
.. note:: Path names have to be set in respect of the installed PHP
129-
(8.1, 8.2, 8.3 or 8.4) as applicable.
119+
``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar``
120+
121+
--------------------------------
122+
PHP Modules for Media Management
123+
--------------------------------
124+
125+
**Image meta data and orientation** (optional):
126+
127+
- `exif`: Image meta data loading and rotation
128+
129+
**Preview Generation** (optional):
130+
131+
- `imagick` (for image previews)
132+
- `avconv` or `ffmpeg` (for video previews)
133+
- OpenOffice or LibreOffice (for document previews)
134+
135+
.. note::
136+
If previewing PDF files fails with a "not authorized" error, you may need to adjust the `imagick` policy file. See https://cromwell-intl.com/open-source/pdf-not-authorized.html
137+
138+
See :doc:`../configuration_files/previews_configuration` for additional preview generation context.
139+
140+
-------------------------------------
141+
PHP Modules for Specific Applications
142+
-------------------------------------
143+
144+
Some optional Nextcloud apps/functionality require additional modules. Install as needed:
145+
146+
- `ldap`: LDAP integration
147+
- `smbclient`: SMB/CIFS integration (see :doc:`../configuration_files/external_storage/smb`)
148+
- `ftp`: FTP storage or external user authentication
149+
- `imap`: External user authentication
150+
151+
**Recommended/Optional:**
152+
153+
- `gmp`: SFTP storage
154+
155+
------------------
156+
PHP `ini` Settings
157+
------------------
158+
159+
Adjust the following settings in your `php.ini` as needed for Nextcloud:
160+
161+
- ``disable_functions``: Avoid disabling functions unless necessary.
162+
- ``max_execution_time``: See :doc:`../configuration_files/big_file_upload_configuration`
163+
- ``memory_limit``: Should be at least 512MB. See also :doc:`../configuration_files/big_file_upload_configuration`
164+
- ``opcache.enable`` and related settings: See :doc:`../configuration_server/caching_configuration` and :doc:`server_tuning`
165+
- ``open_basedir``: See :doc:`harden_server`
166+
- ``upload_tmp_dir``: See :doc:`../configuration_files/big_file_upload_configuration`
167+
168+
--------------------------------
169+
Notes on PHP `ini` Configuration
170+
--------------------------------
171+
172+
- **Multiple php.ini files:**
173+
174+
- You may need to configure settings in more than one `php.ini` file (e.g., for web server and CLI).
175+
176+
- Web server:
177+
`/etc/php/<version>/apache2/php.ini` or `/etc/php/<version>/fpm/php.ini`
178+
179+
- CLI (used by Nextcloud CRON jobs):
180+
`/etc/php/<version>/cli/php.ini`
181+
182+
- **Find which php.ini is active for each SAPI:**
183+
184+
- Use ``php --ini`` for CLI, or check ``phpinfo()`` in a web page.
185+
186+
- **Search for a parameter:**
187+
188+
- Run ``grep -r <parameter_name> /etc/php`` (e.g., ``grep -r date.timezone /etc/php``)
189+
190+
- **Replace `<version>` with your actual PHP version (e.g., 8.1, 8.2, etc.).**
191+
192+
--------------------------------
193+
PHP Module Quick Reference Table
194+
--------------------------------
195+
196+
+------------------+----------+-------------+------------------+-----------------------------------------------+
197+
| Module | Required | Recommended | For Specific App | Description |
198+
+==================+==========+=============+==================+===============================================+
199+
| ctype | ✓ | | | Core functionality |
200+
+------------------+----------+-------------+------------------+-----------------------------------------------+
201+
| curl | ✓ | | | HTTP requests |
202+
+------------------+----------+-------------+------------------+-----------------------------------------------+
203+
| intl | | ✓ | | Improves translations and sorting |
204+
+------------------+----------+-------------+------------------+-----------------------------------------------+
205+
| sodium | | ✓ | | Argon2 password hashing |
206+
+------------------+----------+-------------+------------------+-----------------------------------------------+
207+
| ldap | | | ✓ | LDAP integration |
208+
+------------------+----------+-------------+------------------+-----------------------------------------------+
209+
| smbclient | | | ✓ | SMB/CIFS integration |
210+
+------------------+----------+-------------+------------------+-----------------------------------------------+
211+
| ftp | | | ✓ | FTP storage/authentication |
212+
+------------------+----------+-------------+------------------+-----------------------------------------------+
213+
| imap | | | ✓ | External user authentication |
214+
+------------------+----------+-------------+------------------+-----------------------------------------------+
215+
| gmp | | | ✓ (optional) | SFTP storage |
216+
+------------------+----------+-------------+------------------+-----------------------------------------------+
217+
| exif | | | ✓ (optional) | Image rotation in Pictures app |
218+
+------------------+----------+-------------+------------------+-----------------------------------------------+
219+
| apcu | | ✓ | | Performance caching |
220+
+------------------+----------+-------------+------------------+-----------------------------------------------+
221+
| memcached | | ✓ | | Performance caching |
222+
+------------------+----------+-------------+------------------+-----------------------------------------------+
223+
| redis | | ✓ | | Transactional File Locking |
224+
+------------------+----------+-------------+------------------+-----------------------------------------------+
225+
| imagick | | | ✓ (optional) | Image previews |
226+
+------------------+----------+-------------+------------------+-----------------------------------------------+
227+
| avconv/ffmpeg | | | ✓ (optional) | Video previews |
228+
+------------------+----------+-------------+------------------+-----------------------------------------------+
229+
| Open/LibreOffice | | | ✓ (optional) | Document previews |
230+
+------------------+----------+-------------+------------------+-----------------------------------------------+
231+
| pcntl | | | ✓ (optional) | Command interruption in CLI |
232+
+------------------+----------+-------------+------------------+-----------------------------------------------+
233+
| phar | | | ✓ (optional) | Needed for command-line updater |
234+
+------------------+----------+-------------+------------------+-----------------------------------------------+
235+
236+
-----------------
237+
Further Resources
238+
-----------------
239+
240+
- For more details on each module, consult the
241+
`official PHP documentation <https://php.net/manual/en/extensions.php>`_.
242+
- Refer to your OS distribution's documentation for the specifics of installing PHP modules in your environment.
243+
- The words *extension* and *module* are interchangeable within PHP. We use the word *modules* in our documentation.
244+
- Always restart your web server and PHP-FPM after making changes to an `php.ini` file or installed modules.

‎go.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
'admin-oauth2' => '/admin_manual/configuration_server/oauth2.html',
3636
'admin-performance' => '/admin_manual/installation/server_tuning.html',
3737
'admin-php-fpm' => '/admin_manual/installation/source_installation.html#php-fpm-tips-label',
38-
'admin-php-modules' => '/admin_manual/installation/php_configuration.html#php-modules',
38+
'admin-php-modules' => '/admin_manual/installation/php_configuration.html#required-php-modules',
3939
'admin-php-opcache' => '/admin_manual/installation/server_tuning.html#enable-php-opcache',
4040
'admin-provisioning-api' => '/admin_manual/configuration_user/user_provisioning_api.html',
4141
'admin-reverse-proxy' => '/admin_manual/configuration_server/reverse_proxy_configuration.html',

0 commit comments

Comments
 (0)