Savvas Alexandrou edited this page Dec 12, 2017 · 35 revisions

How to see the variants of the installed PHPs?

phpbrew list --variants 
phpbrew list -v             # for abbr

How to see the install prefix of the installed PHPs?

phpbrew list --dir 
phpbrew list -d             # for abbr

How to install the same PHP version with different variants?

You build the first:

phpbrew install 5.5.17 +intl+icu

And you can inherit the variants and install as a different build by adding the --alias option:

phpbrew install 5.5.17 like php-5.5.17-default as php-5.5.17-debug +debug
phpbrew --debug install 7.0.5 like 7.0.5-debug as aaa

Switch between the different builds:

phpbrew use php-5.5.17-debug
phpbrew use php-5.5.17

Specifying mirror site

phpbrew 1.15 already shipped with the --mirror [URL] option, you may use the option to choose the mirror site instead of the default one:

$ phpbrew install --mirror 5.3.22
$ phpbrew install --mirror 5.5.10

Using ramdisk to build PHP

PHPBrew has a out of the box feature that you can specify the directory for building your PHP just like this:

$ phpbrew install --build-dir /Volumes/ramdisk/phpbrew/build php-5.3.29 +default+intl

And you can combine the technics of creating RAM disk. for example, on Mac OS X, you can do this as root:

sudo -i

SIZE=$((1 * 1024 * 2 * 1024))
RAMDISK_DEV=`hdiutil attach -nomount ram://$SIZE`
diskutil erasevolume HFS+ "ramdisk" $RAMDISK_DEV
diskutil enableOwnership /Volumes/ramdisk

On Linux, you can use ramdisk with tmpfs:

mount -o size=1G -t tmpfs none /mnt/tmpfs

It requires around ~300MB to build one PHP release, if you want to build more PHP releases, you will need a larger ramdisk.

Setting up prefered lookup prefix

phpbrew automatically detects the library prefix and include prefix for each different variant. for example, if you want to include gd extension support, phpbrew finds if gd2.h exists in your include prefix.

Now you can specify your prefered lookup prefix for HomeBrew, Macports, Linux or setup your customized prefix for the library prefix auto-lookup.

If you're using HomeBrew, you can simply type:

phpbrew lookup-prefix homebrew

After you setup the lookup prefix, phpbrew will do all the stuff automatically.

let's take the +gd variant as an example, when you install php with +gd variant, phpbrew expands the options to:

--with-gd=/usr/local/Cellar \
    --with-png-dir=/usr/local/Cellar \
    --with-jpeg-dir=/usr/local/Cellar \
    --with-freetype-dir=/usr/local/Cellar  \

If you're using Macports, simply type:

phpbrew lookup-prefix macports

Then the same variant above can be expanded to:

--with-gd=/opt/local --with-png-dir=/opt/local \
    --with-jpeg-dir=/opt/local \
    --with-freetype-dir=/opt/local  \

You may also specify your custom prefix by typing:

phpbrew lookup-prefix ~/local

Again, the options can be expanded to:

--with-gd=~/local --with-png-dir=~/local \
    --with-jpeg-dir=~/local \
    --with-freetype-dir=~/local  \

GD support

To compile php with gd library support:

phpbrew install 5.4.12 +gd

This will detect paths of freetype, libpng, libjpeg library and expand to the options below:

--with-gd=$prefix --with-png-dir=$prefix --with-jpeg-dir=$prefix --with-freetype-dir=/opt/local --enable-gd-native-ttf

If it shows references not found, you may specify +gd variant with shared value. e.g.,

phpbrew install 5.4.12 +gd=shared

The command above compiles your gd extension into (shared library)

How to install the IMAP extension?

First, install its dependencies (this should work for a pretty wide range of Ubuntu versions):

sudo apt install libc-client2007e libc-client2007e-dev libkrb5-dev

Then install the extension itself:

phpbrew ext install imap -- --with-imap-ssl --with-kerberos

Apache2 support

To compile php with apache2 SAPI support:

phpbrew install 5.4.12 +apxs2

This will find your apxs2 binary automatically. If you have different apxs2 under different paths on your system, you may specify apxs2 with the full path, for example if you need to compile your php with apache2 support (installed by Macports):

phpbrew install 5.4.12 +apxs2=/opt/local/apache2/bin/apxs

This will patch the configure script to let you install the php module with different version.

But you still have to modify the config file manually if you need to change the php version.


  1. If you want to build php with apache php module, please change the permission of apache module directory, eg: /opt/local/apache2/modules/. it should be writable and phpbrew should be able to change permission. after install, you should check your httpd.conf configuration file, to switch your php module version. :-)

  2. phpbrew currently only supports for apxs2 (apache2)

If you enabled the apxs2 variant, your apache conf file might look like this if you have multiple php(s) installed on your system:

# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
# LoadModule php5_module        modules/
LoadModule php5_module          modules/

You can simply uncomment/comment it to enable the php5 apache module you needed, after modifying it, remember to restart your apache http server. :)

Also, make sure that Apache is configured to handle PHP files using the module:

AddType application/x-httpd-php .php

OpenSSL support

If you want to compile php with openssl support, you just add the openssl variant

phpbrew install 5.4.12 +openssl

And phpbrew will find your openssl include path automatically.

If you need to compile with speicific openssl library, simply add the path after the openssl variant:

phpbrew install 5.4.12 +openssl=/opt/local

If you need to compile the openssl as a shared library:

phpbrew install 5.4.12 +openssl=shared

On 64 bit Fedora systems it is necessary to use the --with-libdir flag to locate the library:

phpbrew install 5.4.12 +openssl=shared -- --with-libdir=lib64

Compile php with extra options

If you want to use extra configure options, which are not included in phpbrew variants, You may append a -- double dash to separate your custom options, e.g.,

phpbrew install 5.4.12 -- --with-freetype-dir=/opt/local --with-png-dir=/opt/local

Install phpbrew into system-wide environment

First, sudo as a root user or login as a root user:

sudo -i

Now initialize your phpbrew bashrc for root:

phpbrew init

Now export phpbrew paths to your desired paths, edit your ~/.phpbrew/init

export PHPBREW_ROOT=/opt/phpbrew
export PHPBREW_HOME=/opt/phpbrew

Source your phpbrew bashrc

source ~/.phpbrew/bashrc

Install system-wide php(s):

phpbrew install php-5.4.5 +default +dbs

Now your php(s) will be installed under the /opt/phpbrew path, To let your users can use php(s) built by phpbrew, you need to export PHPBREW_ROOT and PHPBREW_HOME environment in /etc/bashrc or in /etc/profile.d/ for bash users, before they load the phpbrew/bashrc file.

export PHPBREW_ROOT=/opt/phpbrew
export PHPBREW_HOME=/opt/phpbrew
source /opt/phpbrew/bashrc

To keep system's safety, please use root to install php(s).

a non-root user should not be able to install new php or switch

and remember to fix permissions if these files were installed by non-root user.

chown -R root: /opt/phpbrew

OPCache Support

Compile php with OPCache support:

phpbrew install 5.5.5 +opcache

How do I apply a patch before building my PHP?

Simply specify the option to apply a patch:

phpbrew install --patch [File Path] 5.4.22

Please see the related issue here:

How do I install libevent extension?

phpbrew ext install libevent latest -- --with-libevent=/opt/local

How to install yaml extension?

phpbrew ext install yaml -- --with-yaml=/opt/local

How to install pecl_http?

Before installing pecl_http you need to install raphf first:

phpbrew ext install raphf
phpbrew ext install propro

And then..

For HomeBrew users:

phpbrew ext install pecl_http

For MacPorts users:

phpbrew ext install pecl_http -- --with-http-zlib-dir=/opt/local --with-http-libcurl-dir=/opt/local --with-http-libevent-dir=/opt/local

If you saw undefined symbol: php_persistent_handle_abandon

phpbrew ext clean --purge pecl_http
phpbrew --debug ext install pecl_http 1.7.6 -- --with-http-curl-requests=/opt/local --with-http-curl-libevent=/opt/local --with-http-zlib-compression=/opt/local

How to install Imagick extension?

For Debian and Ubuntu users libmagickwand-* packages are required:

apt-get install libmagickwand-dev libmagickcore-dev
phpbrew ext install imagick 

For OSX users, you have to specify the prefix of your Magick-config. for me, it's /opt/local/bin/Magick-config, therefore I specify /opt/local as my configuration:

phpbrew --debug ext install imagick 3.1.2 -- --with-imagick=/opt/local

If you use Debian Jessie you may encounter the following error:

checking ImageMagick MagickWand API configuration program... configure: error: not found. Please provide a path to MagickWand-config or Wand-config program.

The configure script only checks /usr/bin and /usr/local/bin for the binaries but Debian places them in /usr/lib/x86_64-linux-gnu/ImageMagick-6.8.9/bin-Q16 (see To allow the extension installer to find the binaries you should create two symlinks:

sudo ln -s /usr/lib/x86_64-linux-gnu/ImageMagick-6.8.9/bin-Q16/MagickWand-config /usr/bin/
sudo ln -s /usr/lib/x86_64-linux-gnu/ImageMagick-6.8.9/bin-Q16/Wand-config /usr/bin/

As an extension developer, I want to build a PHP with debug / zts support

$ phpbrew install --name 5.6-debug 5.6 +default +zts +debug

Installing bash completion support

You can get the generated bash completion script from GitHub or you can generate one yourself:

cd /usr/local/share/bash-completion/completions && curl -O

How to use with Lighttpd (Ubuntu)

First, Lighttpd has to be installed via sudo apt-get install lighttpd or sudo aptitude install lighttpd.

The next step is to tell Lighttpd which php-cgi binary should be used. This could be added to the config manually and updated every time the PHP version is switched.

But instead you can do this dynamically. For that include a startup script at the end of /etc/lighttpd/lighttpd.conf by adding this line:

include_shell "/etc/lighttpd/fastcgi.php"

Then create the script at /etc/lighttpd/fastcgi.php with the following contents (see comments for further explanation):

#!/usr/bin/env php
// This script isn't run in the environment context of the acting user.
// So the next variable MUST be set to the user where phpbrew is installed, otherwise it's impossible to fetch the correct path of the php-cgi binary
$ENV_USER = 'daniel';
// This executes the bashrc from the environment user so that the correct path to the binary can be extracted
$path = `su - $ENV_USER -c '. ~/.phpbrew/bashrc; echo \$PHPBREW_PATH'`;
$path = trim($path).'/php-cgi';
server.modules += ( "mod_fastcgi" )

fastcgi.server = ( ".php" =>
    "socket" => "/tmp/php.socket",
    "bin-path" => "<?php echo $path; ?>",
    "bin-environment" => (
      "PHP_FCGI_CHILDREN" => "16",
      "PHP_FCGI_MAX_REQUESTS" => "10000"
    "min-procs" => 1,
    "max-procs" => 1,
    "idle-timeout" => 20

And make it executable

chmod +x /etc/lighttpd/fastcgi.php

After you've checked, that you set your environment user, you're ready to go. Just execute

sudo service lighttpd restart

To verify that it worked, you can add a file info.php to your server.document-root (usually /var/www) with

<?php phpinfo()

Then open http://localhost/info.php and you should see something along these lines in the header: PHP Version 5.6.4 (the current used version).
After switching to another version and restarting the server...

$ phpbrew switch php-5.3.10
$ sudo service lighttpd restart

... the header will show the changed version: PHP Version 5.3.10

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.