Brew & manage PHP versions in pure PHP at HOME
Makefile PHP Shell
Latest commit e10237f Feb 9, 2017 @c9s c9s Fix --cache-file option escape
Failed to load latest commit information.
.github update issue template Apr 27, 2016
assets add php7 info Dec 4, 2015
bin Release 1.21.5 May 9, 2016
build Keep build dir Dec 5, 2015
completion updates completion files Oct 27, 2015
flavors/command Import command flavor for genphp Sep 28, 2014
screenshots update screenshots Jun 13, 2016
scripts Remove old bump-version script Apr 22, 2016
sh Moved files to sh directory Jan 22, 2014
shell Merge pull request #792 from morozov/issue-782 Nov 17, 2016
src/PhpBrew Fix --cache-file option escape Feb 9, 2017
tests Removed failing test: Nov 7, 2016
.gitattributes Release 1.21.4 May 6, 2016
.gitignore Fix build Dec 7, 2015
.hhconfig Add .hhconfig for vim-hack plugin Sep 28, 2014
.travis.yml REMOVE ccache compiler cache content env var Jun 13, 2016 change log for 1.22.5 & 1.22.6 Nov 8, 2016 Update Dec 31, 2015 Replace patches using sed and perl with pure php. Dec 15, 2014
Doxyfile Update Doxyfile for QUIET mode Jul 12, 2012 Update Hacking doc Dec 6, 2015
LICENSE Happy New Year Jan 7, 2015
Makefile create directory if not exists Nov 8, 2016 Update Japanese and English READMEs Jan 18, 2017 fix #834 Jan 28, 2017 add file and translating Feb 29, 2016
build.xml Update phpunit.xml file for logging Jul 21, 2015
composer.json update branch alisa Jun 13, 2016
composer.lock Release 1.21.4 May 6, 2016
phpbrew update phar Nov 9, 2016
phpbrew.asc Add gpg signing rule in Makefile Dec 7, 2015
phpdox.xml Update ant build file Jul 21, 2015
phpmd.xml Update ant build file Jul 21, 2015
phprelease.ini Update release step Apr 22, 2016
phpunit.xml.dist Add PHPBREW_BIN to phpunit config May 4, 2016 update todo Dec 3, 2013


Read this in other languages: English, Português - BR, 日本語.

Build Status Coverage Status StyleCI Gitter

phpbrew builds and installs multiple version php(s) in your $HOME directory.

What phpbrew can do for you:

  • Configure options are simplified into variants, no worries about the path anymore!
  • Build php with different variants like PDO, mysql, sqlite, debug ...etc.
  • Compile apache php module and separate them by different versions.
  • Build and install php(s) in your home directory, so you don't need root permission.
  • Switch versions very easily and is integrated with bash/zsh shell.
  • Automatic feature detection.
  • Install & enable php extensions into current environment with ease.
  • Install multiple php into system-wide environment.
  • Path detection optimization for HomeBrew and MacPorts.


Please see Requirement before you get started. you need to install some development packages for building PHP.


curl -L -O
chmod +x phpbrew

# Move phpbrew to somewhere can be found by your $PATH
sudo mv phpbrew /usr/local/bin/phpbrew


Please see Quick Start if you're impatient. :-p


OK, I assume you have more time to work on this, this is a step-by-step tutorial that helps you get started.

Setting up

Init a bash script for your shell environment:

phpbrew init

Add these lines to your .bashrc or .zshrc file:

[[ -e ~/.phpbrew/bashrc ]] && source ~/.phpbrew/bashrc

For fish shell users, add following lines to your ~/.config/fish/ file:

source ~/.phpbrew/

If you're using system-wide phpbrew, you may setup a shared phpbrew root, for example:

mkdir -p /opt/phpbrew
phpbrew init --root=/opt/phpbrew

Setting up lookup prefix

You may setup your prefered default prefix for looking up libraries, available options are macports, homebrew, debian, ubuntu or a custom path:

For Homebrew users:

phpbrew lookup-prefix homebrew

For Macports users:

phpbrew lookup-prefix macports

Basic usage

To list known versions:

phpbrew known

7.0: 7.0.3, 7.0.2, 7.0.1, 7.0.0 ...
5.6: 5.6.18, 5.6.17, 5.6.16, 5.6.15, 5.6.14, 5.6.13, 5.6.12, 5.6.11 ...
5.5: 5.5.32, 5.5.31, 5.5.30, 5.5.29, 5.5.28, 5.5.27, 5.5.26, 5.5.25 ...
5.4: 5.4.45, 5.4.44, 5.4.43, 5.4.42, 5.4.41, 5.4.40, 5.4.39, 5.4.38 ...
5.3: 5.3.29, 5.3.28 ...

To show more minor versions:

$ phpbrew known --more

To update the release info:

$ phpbrew update

To get older versions (less than 5.4)

Please note that we don't guarantee that you can build the php versions that are not supported by offical successfully, please don't fire any issue about the older versions, these issues won't be fixed.

$ phpbrew update --old

To list known older versions (less than 5.4)

$ phpbrew known --old

Starting Building Your Own PHP

Simply build and install PHP with default variant:

$ phpbrew install 5.4.0 +default

Here we suggest default variant set, which includes most commonly used variants, if you need a minimum install, just remove the default variant set.

You can enable parallel compilation by passing -j or --jobs option and the following is an example:

$ phpbrew install -j $(nproc) 5.4.0 +default

With tests:

$ phpbrew install --test 5.4.0

With debug messages:

$ phpbrew -d install --test 5.4.0

To install older versions (less than 5.3):

$ phpbrew install --old 5.2.13

To install the next (unstable) version:

$ phpbrew install next as php-7.1.0

To install from a github tag:

$ phpbrew install github:php/php-src@PHP-7.0 as php-7.0.0

Cleaning up build directory

$ phpbrew clean php-5.4.0


PHPBrew arranges configure options for you, you can simply specify variant name, and phpbrew will detect include paths and build options for configuring.

PHPBrew provides default variants and some virtual variants, to the default variants, which includes the most commonly used variants, to the virtual variants, which defines a variant set, you may use one virtual variant to enable multiple variants at one time.

To check out what is included in these variants, simply run variants subcommand to list these variants:

$ phpbrew variants
  all, apxs2, bcmath, bz2, calendar, cgi, cli, ctype, dba, debug, dom, embed,
  exif, fileinfo, filter, fpm, ftp, gcov, gd, gettext, hash, iconv, icu,
  imap, intl, ipc, ipv6, json, kerberos, mbregex, mbstring, mcrypt, mhash,
  mysql, openssl, pcntl, pcre, pdo, pgsql, phar, posix, readline, session,
  soap, sockets, sqlite, tidy, tokenizer, xml_all, xmlrpc, zip, zlib, gmp

Virtual variants:
  dbs:      sqlite, mysql, pgsql, pdo
  mb:       mbstring, mbregex
  default:  filter, dom, bcmath, ctype, mhash, fileinfo, pdo, posix, ipc,
            pcntl, bz2, zip, cli, json, mbstring, mbregex, calendar, sockets, readline,

Using variants to build PHP:

  phpbrew install 5.3.10 +default
  phpbrew install 5.3.10 +mysql +pdo
  phpbrew install 5.3.10 +mysql +pdo +apxs2
  phpbrew install 5.3.10 +mysql +pdo +apxs2=/usr/bin/apxs2

To enable one variant, simply add a prefix + before the variant name, eg


To disable one variant, simply add a prefix - before the variant name.


For example, if we want to build PHP with the default options and database supports (mysql, sqlite, postgresql), you may simply run:

$ phpbrew install 5.4.5 +default+dbs

You may also build PHP with extra variants:

$ phpbrew install 5.3.10 +mysql+sqlite+cgi

$ phpbrew install 5.3.10 +mysql+debug+pgsql +apxs2

$ phpbrew install 5.3.10 +pdo +mysql +pgsql +apxs2=/usr/bin/apxs2

To build PHP with pgsql (PostgreSQL) extension:

$ phpbrew install 5.4.1 +pgsql+pdo

Or build pgsql extension with postgresql base dir on Mac OS X:

$ phpbrew install 5.4.1 +pdo+pgsql=/opt/local/lib/postgresql91/bin

The pgsql path is the location of pg_config, you could find pg_config in the /opt/local/lib/postgresql91/bin

To build PHP with neutral compile options, you can specify neutral virtual variant, which means that phpbrew doesn't add any additional compile options including --disable-all. But some options(for example --enable-libxml) are still automatically added to support pear installation. You can build PHP with neutral:

$ phpbrew install 5.4.1 +neutral

For more details, please check out PHPBrew Cookbook.

Extra Configure Options

To pass extra configure arguments, you can do this:

$ phpbrew install 5.3.10 +mysql +sqlite -- \
    --enable-ftp --apxs2=/opt/local/apache2/bin/apxs

Use And Switch

Use (switch version temporarily):

$ phpbrew use 5.4.22

Switch PHP version (switch default version)

$ phpbrew switch 5.4.18

Turn Off:

$ phpbrew off

If you enable apache PHP modules, remember to comment out or remove the settings.

$ sudo vim /etc/httpd/conf/httpd.conf
# LoadModule php5_module        /usr/lib/httpd/modules/
# LoadModule php5_module        /usr/lib/httpd/modules/

List installed PHP

$ phpbrew list

The Extension Installer

See Extension Installer

Configuring the php.ini for current php version

Simply run:

$ phpbrew config

You may specify the EDITOR environment variable to your favorite editor:

export EDITOR=vim
phpbrew config

Upgrade phpbrew

To upgrade phpbrew, you may simply run the self-update command, this command enables you to install the latest version of master branch from GitHub:

$ phpbrew self-update

The Installed PHP(s)

The installed phps are located in ~/.phpbrew/php, for example, php 5.4.20 is located at:


And you should put your configuration file in:


Extension configuration files should be put in:

... etc

Quick commands to switch between directories

Switching to PHP build directory

$ phpbrew build-dir

Switching to PHP dist directory

$ phpbrew dist-dir

Switching to PHP etc directory

$ phpbrew etc-dir

Switching to PHP var directory

$ phpbrew var-dir


phpbrew also provides useful fpm managing sub-commands. to use them, please remember to enable +fpm variant when building your own php.

To start php-fpm, simply type:

$ phpbrew fpm start

To stop php-fpm, type:

$ phpbrew fpm stop

To show php-fpm modules:

phpbrew fpm module

To test php-fpm config:

phpbrew fpm test

To edit php-fpm config:

phpbrew fpm config

The installed php-fpm is located in ~/.phpbrew/php/php-*/sbin.

The correspond php-fpm.conf is located in ~/.phpbrew/php/php-*/etc/php-fpm.conf.default, you may copy the default config file to the desired location. e.g.,

cp -v ~/.phpbrew/php/php-*/etc/php-fpm.conf.default

php-fpm --php-ini {php config file} --fpm-config {fpm config file}

Installing Extra Apps

phpbrew provides app command to fetch some php apps.

Installing composer

$ phpbrew app get composer

Installing phpunit

phpbrew app get phpunit

Enabling Version Info Prompt

To add PHP version info in your shell prompt, you can use "PHPBREW_SET_PROMPT=1" variable.

The default is "PHPBREW_SET_PROMPT=0" (disable). To enable it, you can add this line to your ~/.bashrc file and put this line before you source ~/.phpbrew/bashrc.


To embed version info in your prompt, you can use phpbrew_current_php_version shell function, which is defined in .phpbrew/bashrc. and you can set the version info in your PS1 var. e.g.

PS1=" \$(phpbrew_current_php_version) \$ "

Known Issues

  • For PHP-5.3+ versions, "Building intl 64-bit fails on OS X"

  • To build PHP with GD extension, you need to specify your libpng dir and libjpeg dir, for example,

    $ phpbrew install php-5.4.10 +default +mysql +intl +gettext +apxs2=/usr/bin/apxs2 \ -- --with-libdir=lib/x86_64-linux-gnu \ --with-gd=shared \ --enable-gd-natf \ --with-jpeg-dir=/usr \ --with-png-dir=/usr


Please see TroubleShooting


Q: How do I have the same version with different compile option?

A: Currently, you can install php5.x.x and rename the /Users/phpbrew/.phpbrew/php/php-5.x.x folder to the new name, for example, php-5.x.x-super , and install another php-5.3.3


Please see Contribution


Please see Wiki


  • Yo-An Lin (c9s)
  • Márcio Almad


See LICENSE file.