From Gentoo Wiki
Revision as of 17:31, 27 February 2014 by Fturco (Talk | contribs) (added a Path template)

Jump to: navigation, search
External resources

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



Portage knows the global USE flag php for enabling support for PHP in other packages. Enabling this USE flag will pull in dev-lang/php automatically:


USE="... php ..."

This is a deprecated template. Help us update this template! The most important USE flags of php, the SAPI (Server API) USE flags, are:

USE flag (what is that?) Default Recommended Description
apache2 No Add Apache2 support
cgi No Add CGI script support
cli Yes Enable CLI SAPI
embed No Enable embed SAPI
fpm No Enable the FastCGI Process Manager SAPI

Also check the other USE flags.

By default the ebuild installs the development php.ini version. If you want to install the production version add the following to your make.conf:



This is a deprecated template. Help us update this template! Both versions of php.ini can be found in /usr/share/doc/php-*.

After changing the preferred version of php.ini, you need to reinstall PHP:

root #emerge --oneshot dev-lang/php


If you want to install extensions, you can decide which versions of PHP you want extensions compiled for. This is done by setting the PHP_TARGETS variable:



This is a deprecated template. Help us update this template! You can also set more than one. Note that the php slot is named "5.4" and the corresponding PHP_TARGETS setting is php5-4. This is due to current restrictions on USE names.

After setting this you want to update your system so the changes take effect:

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


To install Nginx is as easy as emerging it:

root #emerge --ask nginx
If you have configured a custom NGINX_MODULES_HTTP , 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:


        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$ {
                        include fastcgi.conf;

This is a deprecated template. Help us update this template!

Now just start the related services and you should have a working site

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


Interestingly enough, you do NOT want the php USE flag for www-servers/lighttpd . It could actually break the build.

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


www-servers/lighttpd fastcgi -php

This is a deprecated template. Help us update this template!

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 we disabled the php USE flag, it won’t 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 so that it looks something like this:


server.modules += ("mod_fastcgi")
fastcgi.server = ( ".php" =>
  ( "localhost" =>
      "host" => "",
      "port" => "9000"

This is a deprecated template. Help us update this template!

Note the host and port parts.

Since Gentoo ships with a perfectly working copy of a php-fpm.ini file, located in /etc/php/fpm-php5/php-fpm.ini , and init-script, all you need to do now is to start the services:

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

Apache (mod_php)

To configure Apache to load your PHP5 module (mod_php), you have to add -D PHP5 to APACHE2_OPTS variable in /etc/conf.d/apache2 .

File/etc/conf.d/apache2Configure Apache to load mod_php

## (settings for PHP5)

This is a deprecated template. Help us update this template!

Php must be compiled with apache2 use flag to serve php.
You can not use two different PHP modules with Apache at the same time.

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-admin/eselect-php package which should get pulled in automatically with your installation. This allows you to run, for example, PHP 5.3 for your cli SAPI but PHP 5.4 on your web server. It also allows you to quickly test your application on different versions of PHP.

To list the available versions for the cli SAPI use:

root #eselect php list cli
 [1]   php5.3
 [2]   php5.4 *
 [3]   php5.5

The version marked with the * is the current active version, and to check the other SAPIs simply replace cli with fpm,cgi,apache2.

To swap versions use:

root #eselect php set cli 1

where 1 corresponds to the number in the output of "show".

You are now running PHP 5.3 on command line.

root #php -v
PHP 5.3.9-pl0-gentoo (cli) (built: Jan 30 2012 13:21:46)


The PHP configuration is in /etc/php, which contains one subdirectory for each SAPI for each PHP version, e.g. configuration files for the PHP-5.4 apache2 SAPI are installed in /etc/php/apache2-php5.4.

To setup Apache to use PHP, see the Apache article.

Replacing PHP 5.4 with PHP 5.5

Set the PHP_TARGETS variable.



This is a deprecated template. Help us update this template!


Install PHP 5.5:

root #emerge --ask dev-lang/php:5.5

Replacing APC

If you are building with the opcache USE flag (the default) but need APC user-land functions such as apc_fetch(), install APCu, which emulates APC but only has user caching functions. This may be necessary for older projects that rely on APC for caching.

If necessary, unmask it:

root #echo 'dev-php/pecl-apcu ~amd64' >> /etc/portage/package.use/your-preferred-file

Install APCu:

root #emerge --ask dev-php/pecl-apcu

Switch to PHP 5.5

Switch to it using eselect for all SAPIs:

root #eselect php set cli php5.5
root #eselect php set fpm php5.5

If you have other SAPIs, be sure to run eselect for those as well.

Re-install compatible extensions

Since changing PHP_TARGETS is technically a USE flag change, you will be able to simply emerge @world with flags checking for new USE flags and all extensions should re-build.

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

Uninstall incompatible extensions

Remove all old extensions that do not build for PHP 5.5. I recommend using eix for this task. Note that when piping to emerge, you cannot use interactive mode so --ask on the emerge command is not applicable here.

root #emerge --ask eix
root #eix -I --use php_targets_php5-4 --not --use php_targets_php5-5 --only-names | xargs emerge -C

Be sure to migrate USE flags if you have specified versions in your package.use file(s).

Since you removed extensions, it may be useful to run a dependency clean up at this point for older ones that are no longer compatible.

root #emerge --ask --depclean

Migrate the configuration files

The different slots have different configuration paths. Please take care to migrate the configuration files betfore making use of a new slot.

Uninstall PHP 5.4

root #emerge --ask --unmerge dev-lang/php:5.4

Restart PHP-FPM

Restart PHP-FPM if you are using it.

root #/etc/init.d/php-fpm restart