From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

Other languages:
English • ‎italiano • ‎polski • ‎русский • ‎日本語

PHP is a general-purpose server-side scripting language to produce dynamic web pages.


USE flags

The most important USE flags of the PHP package, the SAPI (Server API) USE flags, are apache2, cgi, and fpm. Alongside these flags, there is an elaborate list of flags to enable various features of the PHP interpreter:

USE flags for dev-lang/php The PHP language runtime engine

acl Add support for Access Control Lists global
apache2 Add Apache2 support global
argon2 Enable password hashing algorithm from app-crypt/argon2 local
bcmath Add support for libbcmath local
bzip2 Use the bzlib compression library global
calendar Add support for calendars (not using mcal!) global
cdb Add support for the CDB database engine from the author of qmail global
cjk Add support for Multi-byte character languages (Chinese, Japanese, Korean) global
cli Enable CLI SAPI local
coverage Include gcov symbols for test coverage and lcov reports. Only useful for extension developers, and requires GCC. local
ctype Enable ctype functions local
curl Add support for client-side URL transfer library global
embed Enable embed SAPI local
enchant Add supports Enchant spelling library. local
exif Add support for reading EXIF headers from JPEG and TIFF images global
fileinfo Add fileinfo extension support local
filter Add filter extension support local
firebird Add support for the Firebird relational database global
flatfile Add dbm support for flat files local
fpm Enable the FastCGI Process Manager SAPI local
ftp Add FTP (File Transfer Protocol) support global
gd Adds support for gd (bundled with PHP) local
gmp Add support for dev-libs/gmp (GNU MP library) global
hash Enable the hash extension local
imap Add support for IMAP (Internet Mail Application Protocol) global
inifile Add dbm support for .ini files local
intl Enables the intl extension for extended internalization support local
iodbc Add support for iODBC library global
json Enable JSON support local
ldap Add LDAP support (Lightweight Directory Access Protocol) global
ldap-sasl Add SASL support for the PHP LDAP extension local
libedit Use the libedit library (replacement for readline) global
lmdb Enable support for dev-db/lmdb db backend local
mysql Add mySQL Database support global
mysqli Add support for the improved mySQL libraries global
oci8-instant-client Use dev-db/oracle-instantclient-basic as Oracle provider instead of requiring a full Oracle server install global
opcache Enables built-in opcode cache, replacing pecl-apc et al. local
pcntl Add support for process creation functions local
pdo Enable the bundled PDO extensions local
phar Enables the phar extension to provide phar archive support local
phpdbg Enable the PHP Debug Command Line SAPI (like gdb for php) local
posix Add support for POSIX-compatible functions global
readline Enable support for libreadline, a GNU line-editing library that almost everyone wants global
recode Enable support for the GNU recode library global
session-mm Include dev-libs/mm support for session storage local
sharedmem Add support for shared memory use local
simplexml Support for SimpleXML local
soap Add support for SOAP (Simple Object Access Protocol) global
sodium Enable support for crypto through dev-libs/libsodium local
spell Add dictionary support global
sqlite Add support for sqlite - embedded sql database global
sysvipc Support for System V-compatible inter-process communication local
tidy Add support for HTML Tidy global
tokenizer Add support for the PHP file parser local
tokyocabinet Enable support for dev-db/tokyocabinet db backend local
wddx Add support for Web Distributed Data eXchange local
webp Enable webp support for GD in php-7.x local
xmlreader Enable XMLReader support local
xmlrpc Support for xml-rpc library global
xmlwriter Enable XMLWriter support local
xpm Add support for XPM graphics format global
xslt Enable the XSL extension local
zip-encryption Enable ZIP file encryption from dev-libs/libzip local

The ebuild installs a modified "production" version of php.ini that has tighter security settings and default paths adjusted for Gentoo systems. Both upstream "production" and "development" php.ini files are installed to /usr/share/doc/php-*.


To install extensions, first decide which versions of PHP to compile the extensions for. This is done by setting the PHP_TARGETS variable:

FILE /etc/portage/make.conf

More than one version can be defined; just add in the additional versions separated by a space. Note that the php slot is named "5.6" and the corresponding PHP_TARGETS value is php5-6. This is due to current restrictions on USE names.


After making the above USE flag configurations it is necessary to update the system so the changes take effect:

root #emerge --ask --update --changed-use --deep @world

Running multiple versions of PHP

One of the great advantages of using Gentoo for PHP development is the version slotting. It is very simple to swap between multiple versions of PHP as well as run multiple versions simultaneously. This is all done with the eselect command provided by the app-eselect/eselect-php package which should get emerged in automatically by installing PHP.

For example, selecting different versions of PHP can allow a system to run PHP 7.0 for the cli SAPI but PHP 5.6 for the system's web server. It also allows system administrators or application developers to quickly test an application on different versions of PHP.

To list the available versions for the cli SAPI module use the following syntax:

root #eselect php list cli
 [1]   php5.5 
 [2]   php5.6 *   
 [3]   php7.0

The * (asterisk) marks current active version for the selected module. To check the other SAPIs simply replace cli with fpm,cgi or apache2 modules.

To swap versions, use:

root #eselect php set cli 3

The number 3 in this example corresponds to the number in the output of the list sub-command used above. PHP version 7.0 is now used for the command-line:

root #php -v
PHP 7.0.10-pl0-gentoo (cli) (built: Aug 23 2016 12:38:44) ( NTS )


The PHP configuration is at /etc/php, which contains one subdirectory for each Server API (SAPI) and for each PHP version. For instance, configuration files for the PHP-5.6 apache2 SAPI are installed in /etc/php/apache2-php5.6.

Web servers

To use PHP in a server-side fashion, a web server needs to be installed and configured to use PHP. A number of popular web servers are briefly touched upon next.


Simply emerge nginx to install it:

root #emerge --ask www-servers/nginx
If custom NGINX_MODULES_HTTP values are set in make.conf, make sure that the fastcgi module is enabled.

Once Nginx has been installed, modify the server section of /etc/nginx/nginx.conf to look something like this:

FILE /etc/nginx/nginx.confPart of the nginx configuration to enable PHP through FastCGI
server {
                server_name localhost;
                access_log /var/log/nginx/localhost.access_log main;
                error_log /var/log/nginx/localhost.error_log info;
                root /var/www/localhost/htdocs;
                location ~ \.php$ {
                        try_files $uri $uri/ =404;
                        fastcgi_split_path_info ^(.+\.php)(/.+)$;
                        include fastcgi.conf;

Now start the related services to have a working site. The php-fpm init script starts the PHP FastCGI Process Manager. FastCGI allows web servers to offload the PHP calculations to this process manager.

When running OpenRC as the service manager:

root #rc-service nginx start
root #rc-service php-fpm start

For systemd:

root #systemctl start nginx
root #systemctl start php-fpm@7.2
The version number after the php-fpm service name will change based on the available version of PHP. Adjust as appropriate.


Do not enable the php USE flag for www-servers/lighttpd. It could actually break the build.

Make sure that lighttpd is built with support for fastcgi and that the php USE flag is disabled:

FILE /etc/portage/package.use
www-servers/lighttpd fastcgi -php

Lighttpd ships with a default FastCGI config file, but unfortunately, it is written to work with the old PHP FCGI SAPI only, instead of a general FCGI setup. Since the php USE flag has been disabled, it will not be included, and rightly so. However it does provide a good foundation for a configuration file that can be used with FPM.

Edit /etc/lighttpd/mod_fastcgi.conf to look something like this:

FILE /etc/lighttpd/mod_fastcgi.confEnable FastCGI on lighttpd
server.modules += ("mod_fastcgi")
fastcgi.server = ( ".php" =>
  ( "localhost" =>
      "host" => "",
      "port" => "9000"

Note the host and port parts.

Since Gentoo ships with a working php-fpm.ini file, located in /etc/php/fpm-php5/php-fpm.ini, and init script, starting the services is all that is needed:

root #/etc/init.d/php-fpm start
root #/etc/init.d/lighttpd start

Apache (mod_php)

To configure Apache to load the PHP5 module (mod_php), add -D PHP to APACHE2_OPTS variable in /etc/conf.d/apache2. Users might remember that previously, the PHP version had to be added as well (like -D PHP5). However, since app-eselect/eselect-php version 0.8.1, the variable is changed to just -D PHP to allow future major versions to be easily integrated.

FILE /etc/conf.d/apache2Configure Apache to load mod_php
## (settings for PHP5 and above)

Make sure that PHP is built with the apache2 USE flag.

If for some reason the system is missing the PHP module integration file /etc/apache2/modules.d/70_mod_php.conf, currently provided by app-eselect/eselect-php when installed with apache2 USE flag set, manually insert it. Its current content is displayed below.

FILE /etc/apache2/modules.d/70_mod_php.conf
<IfDefine PHP>
	# The symlink is controlled by
	# eselect-php. However, the module name changed from
	# php5_module to php7_module so we can't blindly load whatever
	# is there. Instead we let eselect-php manage a small
	# configuration file that loads the appropriate module.
	# This is relative to ServerRoot (see httpd.conf).
	Include ../../../var/lib/eselect-php/mod_php.conf
	# Tell apache that mod_php should handle PHP files.
	# NOTE: Avoiding AddHandler/AddType for security (bug
	# #538822). Please read the related news item!
	<FilesMatch "\.(php|php[57]|phtml)$">
		SetHandler application/x-httpd-php
	# PHP source files which are meant to be displayed as
	# syntax-highlighted source code.
	<FilesMatch "\.phps$">
		SetHandler application/x-httpd-php-source
	DirectoryIndex index.php index.phtml

Although multiple PHP versions can be installed on a system, Apache can only use a single PHP version with mod_php. Support for multiple PHP versions on Apache is available using fpm. The eselect php command is used to switch between active mod PHP versions.

See also