Upgrading PHP

1.  Introduction

In the past there have been a lot of requests why PHP5 in portage isn't marked as stable yet. The problem is not the PHP5 package itself, the main reason why PHP5 wasn't marked stable yet is that there are many applications, PHP extensions and packages in portage, which do not work with PHP5, and there is nothing we can do about it. PHP5 isn't 100% backwards compatible with PHP4, and not every PHP4 program can/will be ported to run on PHP5. Many users are going to need PHP4 support for a long time to come.

The solution to solve the problems is to provide a mixed PHP4 / PHP5 environment on the same box at the same time. But that wasn't possible with the current layout of PHP packages and eclasses, so there needed to be put a lot of effort into a new layout, new eclasses and new ebuilds.

This document details how to upgrade without breaking your system.

2.  Changes

Basic PHP Packages Consolidated

All PHP ebuilds dev-php/php, dev-php/php-cgi and dev-php/mod_php have been merged to one ebuild: dev-lang/php.

To choose the SAPI you want, use these USE flags:

• cgi - builds & installs /usr/bin/php-cgi
• cli - builds & installs /usr/bin/php
• apache - builds & installs mod_php for Apache 1.3 (new layout)
• apache2 - builds & installs mod_php for Apache 2.0 (new layout)

You can mix and match any of these USE flags; except you can't have both apache and apache2 switched on.

The whole point of these ebuilds is that you can have both PHP4 and PHP5 installed at the same time:

(install latest version of PHP with CLI and Apache2 module)
USE="cli apache2" emerge 'dev-lang/php'

(install PHP4 only)
USE="cli apache2" emerge '=dev-lang/php-4*'

(install both, PHP4 and PHP5)
USE="cli apache2" emerge '=dev-lang/php-4*' '=dev-lang/php-5*'

New Portage Categories

The new PHP ebuilds have been moved from dev-php to dev-lang/php. To make it possible to install packages independently for PHP4 and PHP5, two new portage categories have been created: dev-php4 and dev-php5. These categories are mainly used by PECL packages like pecl-pdo, pecl-apc, php-java-bridge or xdebug.

To install pecl-apc:

(install APC for PHP4 only)
emerge dev-php4/pecl-apc

(install APC for PHP5 only)
emerge dev-php5/pecl-apc

(install APC for both, PHP4 and PHP5)
emerge dev-php4/pecl-apc dev-php5/pecl-apc

New Directories

• These new ebuilds install their contents into /usr/lib/php4 and /usr/lib/php5 (the Apache modules go into the right place for Apache).
• The PEAR packages and other PHP libraries go into /usr/share/php (was /usr/lib/php before).
• PECL packages will no longer add configuration directives by adding them to the php.ini configuration file, but add a [PACKAGE].ini file to the /etc/php/[SAPI]/ext directory.

Symlinking of PHP binaries

If you install more than one version of PHP, e.g.:

USE="cgi cli apache2" emerge '=dev-lang/php-4*' '=dev-lang/php-5*'

The ebuilds will create symlinks in /usr/bin for the last version of PHP you installed, in this case PHP5 since it was installed after PHP4. If you want /usr/bin/php or /usr/bin/php-cgi to point to PHP4 or one to PHP4, the other to PHP5 etc., you can use the php-select tool from app-admin/php-toolkit. php-select makes it very easy to symlink the appropriate binaries.

3.  Upgrade Instructions

Find Packages to upgrade

First you need to figure out which additional packages you need to upgrade. You can do this using the equery tool, part of the app-portage/gentoolkit package:

$ equery list 'dev-php/'
[ Searching for all packages in 'dev-php' among: ]
 * installed packages
[I--] [  ] dev-php/php-4.4.0 (0)
[I--] [  ] dev-php/mod_php-4.4.0 (1)
[I--] [  ] dev-php/smarty-2.6.10 (0)
[I--] [  ] dev-php/PEAR-PEAR-1.3.5-r1 (0)
[I--] [  ] dev-php/PEAR-Mail-1.1.6 (0)
[I--] [  ] dev-php/PEAR-MDB-1.3.0 (0)
[I--] [  ] dev-php/PECL-apc-3.0.6 (0)
[I--] [  ] dev-php/PECL-imagick-0.9.11 (0)
[I--] [  ] dev-php/xdebug-2.0.0_beta3 (0)

PHP extensions, such as

• PECL-apc
• PECL-imagick
• xdebug

have been splitted into 2 seperate portage categories dev-php4 and dev-php5, to make it possible to use them independently for both PHP versions. Additionally most of these packages have been renamed:

Examples for new directories and renaming:

Remove old Packages

We have made many changes to how PHP works within Gentoo. You have to completely remove your old PHP packages, before installing the new packages:

(unmerge PHP packages)
emerge --unmerge php mod_php

(unmerge PHP extensions)
emerge --unmerge PECL-apc PECL-imagick xdebug

(unmerge PHP libraries/applications)
emerge --unmerge PEAR-PEAR PEAR-Mail PEAR-MDB smarty

Set the USE flags

As we have added some new USE flags, you may want to review them and add appropriate lines to /etc/portage/package.use (has to be created if it doesn't exists).

Please set the USE flags accordingly to what you want your PHP installation to support (it is recommended to at least set the cli USE flag):

dev-lang/php -* cli apache2 ctype expat fastbuild ftp gd hash iconv memlimit mysql nls pcre pic pdo reflection session simplexml sockets spl ssl tokenizer truetype unicode xml xsl zlib

If you want to install PHP4 and PHP5 in parallel, you can put in different USE flags for each version:

=dev-lang/php-4* -* cli cgi apache2 ctype expat fastbuild force-cgi-redirect ftp gd iconv ipv6 memlimit mysql nls pcre pic posix session sockets ssl tokenizer truetype unicode xml xsl zlib
=dev-lang/php-5* -* cli cgi apache2 ctype fastbuild force-cgi-redirect ftp gd hash iconv ipv6 memlimit mysql nls pcre pic posix pdo reflection session simplexml soap sockets spl sqlite ssl tokenizer truetype unicode xml xmlreader xmlwriter xsl zlib

Emerge PHP

Now you have the choice to install PHP4 only, PHP5 only or both in parallel. To install PHP4 only you have to emerge =dev-lang/php-4*, to install PHP5 (latest) you can use dev-lang/php, and to install both in parallel you have to emerge =dev-lang/php-4* and =dev-lang/php-5*.

Check USE flag settings:

(check PHP4 package)
emerge --pretend --verbose '=dev-lang/php-4*'

(check PHP5 package)
emerge --pretend --verbose '=dev-lang/php-5*'

(check PHP extensions for PHP4)
emerge --pretend --verbose dev-php4/pecl-apc dev-php4/pecl-imagick dev-php4/xdebug

(check PHP extensions for PHP5)
emerge --pretend --verbose dev-php5/pecl-apc dev-php5/pecl-imagick

(check PHP libraries/applications)
emerge --pretend --verbose PEAR-PEAR PEAR-Mail PEAR-MDB smarty

Emerge PHP if everything is fine:

(emerge PHP4 package)
emerge '=dev-lang/php-4*'

(emerge PHP5 package)
emerge '=dev-lang/php-5*'

(emerge PHP extensions for PHP4)
emerge dev-php4/pecl-apc dev-php4/pecl-imagick dev-php4/xdebug

(emerge PHP extensions for PHP5)
emerge dev-php5/pecl-apc dev-php5/pecl-imagick

(emerge PHP libraries/applications)
emerge PEAR-PEAR PEAR-Mail PEAR-MDB smarty

PHP4 and PHP5 parallel: select which cli/cgi binary to use

After emerging you will have binaries for cli and/or cgi in /usr/lib/php4/bin and/or /usr/lib/php5/bin. If you have installed both, PHP4 and PHP5, portage cannot decide for you which one should be used by default and always symlinks the last PHP version you installed in /usr/bin. So if you installed PHP5 as last, you'll see /usr/bin/php symlinked to /usr/lib/php5/bin/php. So one cli and/or cgi binary as well as php-devel (responsable for building PHP extensions using phpize and php-config) has to be symlinked (in /usr/bin), which could easily be done using php-select, which is part of app-admin/php-toolkit.

Assuming you have emerged =dev-lang/php-4* as well as =dev-lang/php-5*, enter the following php-select commands to show the currently selected PHP versions:

(for cli)
php-select php

(for cgi)
php-select php-cgi

(for phpize, php-config)
php-select php-devel

You should see something like that:

# php-select php
/usr/bin/php is set to /usr/lib/php5/bin/php

Which means that the default path to the PHP cli binary /usr/bin/php is symlinked to the PHP5 binary /usr/lib/php5/bin/php. So PHP scripts using /usr/bin/php will be executed by PHP5.

Use php-select to change default PHP versions

If you are not happy with the default version settings you found out in the last chapter, you can use php-select again to select the desired version:

(for cli)
php-select php php4

(for cgi)
php-select php-cgi php5

(for phpize, php-config)
php-select php-devel php5

Check linking:

 # stat /usr/bin/php /usr/bin/php-cgi /usr/bin/phpize /usr/bin/php-config | grep File
 File: `/usr/bin/php' -> `/usr/lib/php4/bin/php'
 File: `/usr/bin/php-cgi' -> `/usr/lib/php5/bin/php-cgi'
 File: `/usr/bin/phpize' -> `/usr/lib/php5/bin/phpize'
 File: `/usr/bin/php-config' -> `/usr/lib/php5/bin/php-config'

4.  Migration of configuration files

The Gentoo PHP Package stores configuration in /etc/php, which contains one subdirectory for each SAPI for each PHP version:

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

Every subdirectory contains an own php.ini, like the old packages.

Changes in php.ini

You should use etc-update or dispatch-conf and go through the differences between your old and new settings in php.ini. Two directives you definitely must check are include_path and extension_dir. But be careful here, extension_dir is different between PHP version (also between 5.0, and 5.1!).

Example for PHP 5.1 in /etc/php/apache2-php5/php.ini and /etc/php/cli-php5/php.ini:

include_path = ".:/usr/lib/php"
extension_dir = "/usr/lib/php/extensions/no-debug-non-zts-20050617/"

include_path = ".:/usr/share/php"
extension_dir = "/usr/lib/php5/lib/php/extensions/no-debug-non-zts-20050617/"

Configuration of PHP Extensions changed

The new PHP package does not store configuration directives from external (shared) PHP extensions in php.ini anymore. These directives will be stored in own extension-specific configuration files in the /etc/php/*/ext directories. 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.

If you had dev-php/PECL-apc installed before, APC configuration is stored in your php.ini. If you reemerge the new dev-php5/pecl-apc package, the default configuration of APC will be written to /etc/php/*5/ext/apc.ini.

So you have to move your APC configuration directives from /etc/php/*5/php.ini to /etc/php/*5/ext/apc.ini and create a symlink from /etc/php/*5/ext-active/apc.ini to /etc/php/*5/ext/apc.ini.

5.  Configure Apache to work with PHP4 and/or PHP5

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

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

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

There are many ways to make Apache work with two PHP versions in parallel. The easiest way is to use PHP4 and PHP5 as a cgi binary, or a PHP4 cgi and PHP5 module (or the other way around). It's not possible to use the PHP4 module and PHP5 module in one Apache instance.

We have created a PHP4 and PHP5 Configuration Guide which explains some of the possible solutions.

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

For details about implementation of the new packages have a look at Stuart's Posting on gentoo-dev. You might also find Stuart's PHP Blog interesting.

On the Development-Page you'll find a lot of documentation and more recent ebuilds, which will be moved to the official Portage tree later.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.