Basic PHP Packages Consolidated
There is only one php package (as opposed to one package for each SAPI like
cgi, cli or apache). You can enable the SAPIs you want via USE flags in
dev-lang/php. A list of available SAPIs is included below.
You can combine them as you wish, but obviously you need at least one of
them to make any use of your php installation.
To choose the SAPI you want, use these USE flags:
cgi - builds & installs /usr/bin/php-cgi
cli - builds & installs /usr/bin/php
apache2 - builds & installs mod_php for Apache 2
fpm - builds & installs the PHP FastCgi Process Manager (only available in PHP-5.3 and newer)
embed - builds & installs the embedded PHP client
Minor version slotting
The php team decided to ease the transition between PHP-5.2 and PHP-5.3 by
allowing users to install both versions concurrently. Using the cgi or FPM
SAPI, you can even serve web pages utilizing PHP-5.2 and PHP-5.3 (or PHP-5.4
once it's released) at the same time.
For implementing minor version slotting, we chose an approach similar to
that of the ruby team --- you can set a global variable PHP_TARGETS to
control which slots you want and manage the active version via an eselect
module (see chapter 3)
Switching from major to minor version slotting
Note: Due to popular demand it is now possible to upgrade from major to minor
version slotting without uninstalling php first
Note: If you always want PHP extensions compiled for the last stable PHP version,
you can skip the first step.
Decide which versions of PHP you want extensions compiled for and set them
in your /etc/make.conf.
Code Listing 3.1: Setting PHP_TARGETS in /etc/make.conf
You can set the targets in any order. Note that the php slot is named "5.3"
and the corresponding PHP_TARGETS setting is php5-3. This is due
to current restrictions on USE names.
You can also set PHP_TARGETS
per package like so:
Code Listing 3.2: Setting PHP_TARGETS in package.use
Next, install the PHP versions you want:
Code Listing 3.3: Installing both PHP-5.2 and -5.3
emerge dev-lang/php:5.2 dev-lang/php:5.3
Note that using emerge php is enough to always get the latest stable
Update your extensions. If you have installed PHP extensions such as suhosin
or mailparse, you need to reinstall them.
The php team has provided a
minor version slotting compatible version of every package in the
Code Listing 3.4: Reinstalling all extensions
emerge -av $(equery depends dev-lang/php | egrep -v 'dev-php/|/php' | sed -e 's:^:=:')
Warning: Running both PHP versions with different USE flags is not supported.
You may be able to install packages with differing configurations, but do not file bugs about it breaking.
The php team is working on a solution that will automate this in the future.
Note that PHP_TARGETS is displayed as a USE-expand variable.
Some extensions are not available for all slots (e.g. have not been updated to
work with PHP-5.3). They will indicate this via the USE_PHP variable
Code Listing 3.5: Ebuild for an extension that supports PHP-5.2 only
USE_PHP="php5-2" # default would be "php5-2 php5-3"
Minor version slotting in detail
Symlinking of PHP binaries
The first time you install a minor version slotted PHP, the new eselect php
module is automatically called to set symlinks in /usr/bin to the
PHP binaries in /usr/lib/php5.3/bin (assuming you installed
php-5.3 first). There is one symlink for each fpm, cgi or cli SAPI you enabled
via USE flags. Additionally, a symlink to the apache module in
/usr/lib/php5.3/apache2/ is placed in your apache module directory
if you installed php with USE="apache2".
Ole Markus With kindly provided an eselect module
(app-admin/eselect-php) to manage the symlinks. You can list and update
the active PHP version for each SAPI seperatly. Here is an example using the
Code Listing 4.1: Using the PHP eselect module when you have PHP-5.2 and 5.3 installed
# eselect php list apache2
 php5.3 *
# eselect php set apache2 1
You have to run `/etc/init.d/apache2 restart' for the changes to take effect
The eselect module currently supports fpm, apache2, cli and cgi SAPIs
The Gentoo PHP Package stores configuration in /etc/php, which
contains one subdirectory for each SAPI for each PHP version, e.g.
configuration files for the PHP-5.3 apache2 SAPI are installed in
Code Listing 4.2: list PHP config directories
$ ls -1 /etc/php
Every subdirectory contains an own php.ini, but external
(shared) extension are now kept in their own
/etc/php/&sapi>-&slot>/ext directory. To enable/ disable
shared extensions, symlinks from /etc/php/*/ext-active are used.
If you want to enable an extension, create a symlink in
/etc/php/*/ext-active to the corresponding
&extension>.ini file in /etc/php/*/ext/. If you
want to disable an extension, remove the symlink.
Note: If you install PHP as an Apache module, make sure to restart Apache
after installation and configuration.
Configure Apache to work with PHP5
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.
Code Listing 4.3: Configure Apache to load mod_php
Note: You can not use two different PHP modules with Apache at the same time.
Support / Getting Help
If you run into problems with the new Gentoo PHP packages, here's where you
can get help:
Questions about PHP on Gentoo
Development-Page of the PHP
#gentoo-php on irc.freenode.net; this is the chatroom where the overlay's
regular authors hang out. We'd love to see you there!
Gentoo Forums are a popular
place to ask for help. There are plenty of other Gentoo users reading the
Forums round the clock, making it a great place to get help in a hurry.
On the Development-Page
you'll find a lot of documentation and our git
repository provides a test ground for packages, which will be moved
to the official Portage tree later.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.