Gentoo Logo

Upgrading PHP

Content:

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

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

# 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:

Code Listing 3.2: Setting PHP_TARGETS in package.use

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

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 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.

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

Code Listing 3.5: Ebuild for an extension that supports PHP-5.2 only

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:

Code Listing 4.1: Using the PHP eselect module when you have PHP-5.2 and 5.3 installed

# 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

Code Listing 4.2: list PHP config directories

$ 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.

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

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

Note: You can not use two different PHP modules with Apache at the same time.

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.



Print

Page updated June 5, 2011

Summary: This document describes how PHP is set up in Gentoo.

Andreas Korthaus Matti Bickel Ole Markus With
Author

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.