Upgrading PHP

1.  PHP package

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

2.  Slotting

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)

3.  Switching from major to minor version slotting

Preperations

Decide which versions of PHP you want extensions compiled for and set them in your /etc/make.conf.

# Run PHP 5.3 and PHP 5.2 in parallel
PHP_TARGETS="php5-3 php5-2"

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:

; compile mailparse only for php-5.3
dev-php5/mailparse php_targets_php5-3

Next, install the PHP versions you want:

emerge dev-lang/php:5.2 dev-lang/php:5.3

Note that using emerge php is enough to always get the latest stable version.

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 dev-php5 category.

emerge -av $(equery depends dev-lang/php | egrep -v 'dev-php/|/php' | sed -e 's:^:=:')

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 like this:

EAPI=2
USE_PHP="php5-2" # default would be "php5-2 php5-3"

inherit php-ext-source-r2
[...]

4.  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 apache2 SAPI:

# eselect php list apache2
[1]   php5.2
[2]   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

Configuration files

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 /etc/php/apache2-php5.3

$ ls -1 /etc/php
apache2-php5
cli-php5
cgi-php5

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.

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.

(settings for PHP5)
APACHE2_OPTS="-D PHP5"

5.  Support / Getting Help

If you run into problems with the new Gentoo PHP packages, here's where you can get help:

• Common Questions about PHP on Gentoo
• Development-Page of the PHP Overlay
• #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.