virtPHP is a tool to create isolated PHP environments.

Related tags


virtPHP is a tool for creating and managing multiple isolated PHP environments on a single machine. It's like Python's virtualenv, but for PHP.

virtPHP creates isolated environments so that you may run any number of PHP development projects, all using different versions of PEAR packages and different PECL extensions. You may even specify a different version of PHP, if your system has various installations of PHP.

To install multiple versions of PHP, we suggest taking a look at the phpenv and php-build projects or phpbrew and using virtPHP with them, to manage multiple virtual PHP environments.

*Note: virtPHP is currently only targeted to command line php (php-cli) for nix based systems.

Build Status Coverage Status


Download the virtphp.phar file from the latest release and place it in /usr/local/bin or wherever it's accessible from your PATH.

Optionally, you may clone this repository and build the phar file yourself.


virtPHP is a command-line tool. To get started, you'll probably want to check out what it can do. To do this, just execute it without any arguments, like this:

[email protected]:~$ php virtphp.phar

If you have the phar file set executable (i.e. chmod 755), then you can execute it like this:

[email protected]:~$ ./virtphp.phar

Or, if it's in your PATH, like this:

[email protected]:~$ virtphp.phar

We recommend putting it in your PATH and aliasing it to virtphp, so that you can run it like this:

[email protected]:~$ virtphp

For convenience, the following examples will assume you have simply downloaded virtphp.phar and have not placed it in your PATH or set it executable.

Getting Started

To create a new virtPHP environment, use the create command:

[email protected]:~$ php virtphp.phar create myenv

By default, this will create a new PHP environment in myenv/, using your system PHP as the base.

After creating the environment, you may activate it so that you now use the new environment in your shell:

[email protected]:~$ source myenv/bin/activate

After activating your environment, you'll notice that your shell changes to include the name of your virtPHP environment, like this:

(myenv) [email protected]:~$

And, when you run which php, your shell session reports it is now using PHP from your virtPHP environment:

(myenv) [email protected]:~$ which php

Now, let's install a PECL extension and a PEAR package.

(myenv) [email protected]:~$ pecl install mongo
(myenv) [email protected]:~$ pear config-set auto_discover 1
(myenv) [email protected]:~$ pear install

(I'm not showing any of the console output here, in case you were wondering.)

What's cool here is that you didn't have to use sudo to install these commands, and if you run pear list -a, you'll see both PHPUnit and pecl/mongo listed as being installed. Now, any project running in the current, activated virtPHP environment can make use of these packages.

To return your environment back to normal settings and discontinue using your virtPHP environment, simply use the deactivate command. It doesn't matter where you are when you run it—it's available to your entire virtPHP environment.

(myenv) [email protected]:~$  deactivate

Now, depending on your base environment, when you run pear list -a, you won't see the PHPUnit or pecl/mongo packages that you just installed.

To start up your virtPHP environment again, just source the activate script for the virtPHP environment you want to use.

Altogether, that's pretty neat, huh?

So you've setup one or two or even eleven different environments. Keeping track of all of them in your head can lead to cluster headaches, right? So to list out all the environments you have installed, use the show command.

[email protected]:~$ php virtphp.phar show

This will give you a nice list of all the environments you've created and the path to each.

| Name   | Path                                 |
| mytest | /Users/virtPHP/work/project2/virtphp |
| myenv  | /Users/virtPHP/work/project1/virtphp |

Because virtPHP creates physical folders and files for all of it's work, make sure you use the built in commands for destroying or cloning environments, otherwise things can get messy. However, if an environment does get out of sync you can perform a resync of a particular environment.

[email protected]:~$ php virtphp.phar show --env=myenv --path=/Users/virtPHP/work/RealProject/virtphp

If you do another show, you will see the updated path in the list of your enviornments.

| Name   | Path                                    |
| mytest | /Users/virtPHP/work/project2/virtphp    |
| myenv  | /Users/virtPHP/work/RealProject/virtphp |

Under the Covers

When you create a new virtPHP environment, it creates a new directory and sets up a virtual environment for PHP within it. For example, the myenv/ environment directory looks something like this:

|-- bin/
|   |-- activate
|   |-- composer -> /home/user/myenv/bin/composer.phar*
|   |-- composer.phar*
|   |-- pear*
|   |-- peardev*
|   |-- pecl*
|   |-- php*
|   |-- php-config*
|   |-- phpize -> /usr/bin/phpize*
|   `-- phpunit*
|-- etc/
|   |-- pear.conf
|   `-- php.ini
|-- lib/
|   `-- php/
|       `--
`-- share/
    |-- pear/
    `-- php/

When you activate the environment, the bin/ directory becomes a part of your PATH. When you install a PECL extension, the extension is placed in lib/php/ (as you can see in this example, with, and when you install a PEAR package, it is placed in share/php/ (and console commands are placed in bin/, as you can see in this example with phpunit).

To be helpful, we have already installed Composer for you. When you activate a virtPHP environment, then you have access to the composer command.

Advanced Concepts

Let's say you need to use the same host machine to develop multiple projects, all requiring different versions of PHP and different versions of PECL extensions or PEAR packages. virtPHP was made for this!

Specifying a PHP Build for virtPHP

If you have multiple builds of PHP on your system, you can tell virtPHP which one to use, when creating a new environment.

[email protected]:~$ php virtphp.phar create --php-bin-dir="/home/user/.phpbrew/php/php-5.4.25/bin" project1-env
[email protected]:~$ php virtphp.phar create --php-bin-dir="/home/user/.phpbrew/php/php5.4.25/bin" project2-env

In this case, we have project1-env and project2-env, both of which use PHP 5.4.25. One of the projects, however uses the older pecl/mongo version 1.2 series, while the other project uses the pecl/mongo 1.4 series. virtPHP makes the use of both extensions possible on the same system. Here's how:

[email protected]:~$ source project1-env/bin/activate # Activate project1
(project1-env) [email protected]:~$ pecl install mongo-1.2.12
(project1-env) [email protected]:~$ deactivate
[email protected]:~$ source project2-env/bin/activate # Activate project2
(project2-env) [email protected]:~$ pecl install mongo-1.4.5
(project2-env) [email protected]:~$ deactivate

Now, we are able to use version 1.2.12 of pecl/mongo, when working on project1-env, and we can use version 1.4.5 of pecl/mongo, when working on project2-env. We just need to activate the environment we are working on first.

In the same way, working with different versions of PHP for other projects is simple. For example, in project3-env, we are using PHP 5.5.

[email protected]:~$ php virtphp.phar create --php-bin-dir="/home/user/.phpbrew/php/php-5.5.9/bin" project3-env

Using phpbrew to install multiple PHP versions

In the previous examples, we told virtPHP to use a specific build of PHP when creating new environments. To use virtPHP in this way, you'll need to install different builds of PHP. You can download the source, configure it, and build it on your own, or you may use phpbrew to do this for you.

First, install phpbrew on your system, like this (follow any instructions these commands print to the screen):

[email protected]:~$ curl -L -O
[email protected]:~$ chmod +x phpbrew
[email protected]:~$ sudo mv phpbrew /usr/bin/phpbrew

Then, you should init a bash script for your shell environment, which will place a bashrc file in the ~/.phpbrew folder.

[email protected]:~$ phpbrew init

Then source this file to your .bashrc or .zshrc file with this line:

[email protected]:~$ source ~/.phpbrew/bashrc

Now, we can view and install a few versions of PHP, and control the variants that can be installed with it, with the following commands.

[email protected]:~$ phpbrew known
Available stable versions:
  5.6 versions:    5.6.0
  5.5 versions:    5.5.16, 5.5.15, 5.5.14, 5.5.13, 5.5.12, 5.5.11, 5.5.10, 5.5.9
  5.4 versions:    5.4.32, 5.4.31, 5.4.30, 5.4.29, 5.4.28, 5.4.27, 5.4.26, 5.4.25
  5.3 versions:    5.3.28, 5.3.27, 5.3.26, 5.3.25, 5.3.24, 5.3.23, 5.3.22, 5.3.21

[email protected]:~$ phpbrew install 5.6.0 +default+debug+mysql

This may take a while, so grab a few cups of coffee. phpbrew command shown with the default, debug, and mysql variants included.

Variants can be installed individually, or in 'virtual variants'

[email protected]:~$ 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

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,

After installing the spcified version of phpbrew, we can activate a specific version like this:

[email protected]:~$ phpbrew use php-5.6.0

...switch between different versions:

[email protected]:~$ phpbrew switch php-5.5.16

...or, return to the system version:

[email protected]:~$ phpbrew off

So, why would we need virtPHP, if we can do this? virtPHP goes beyond phpbrew.

With virtPHP, you may install different PECL extensions, different PEAR packages, and manage separate php.ini configs for the same version and build of PHP. This way, projects you are developing that share the same PHP version but different configuration may be developed on the same system using different virtual PHP environments. virtPHP can work together with phpbrew to achieve this.

Known Issues

  • .pearrc not found issue If you get an error stating the script couldn't access the .pearrc file (or can't find it), you can either try changing the permissions on your [USER_DIR]/.pearrc file or remove it entirely. This issue seems to occur sporadically.


If you would like to help, take a look at the list of issues. Fork the project, create a feature branch, and send us a pull request.

To ensure a consistent code base, you should make sure the code follows the coding standards, which we borrowed from Symfony.

Running the Tests

You may use the provided Vagrantfile to start up a VM and run tests in a clean environment. You will need VirtualBox and Vagrant installed on your system.

[email protected]:~$ cd virtphp/
[email protected]:~$ vagrant up
[email protected]:~$ vagrant ssh
[email protected]:~$ cd /vagrant
[email protected]:~$ curl -sS | php
[email protected]:~$ php composer.phar install
[email protected]:~$ ./vendor/bin/phpunit

Building the Phar File

virtPHP is distributed as an executable phar file. The bin/compile script handles building this file. To build the phar file, change to the location of your virtPHP project clone and execute the compile script like this:

[email protected]:~$ ./bin/compile

This should build a file named virtphp.phar in your current directory. You may move this file to wherever you like and use it for creating virtPHP environments.


PHP 5.3.3 or above.


Copyright (c) 2013-2014 Jordan Kasper, Ben Ramsey, Jacques Woodcock

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.


  • `deactivate` conflicts with Python's virtualenv

    `deactivate` conflicts with Python's virtualenv

    Thankfully, virtphp itself doesn't have any other conflicting commands, but deactivate is used by virtualenv already - shouldn't this be renamed?

    enhancement question 
    opened by chrsm 23
  • PSR-2 review complete

    PSR-2 review complete

    Updating project to PSR-2 Standard

    Reviewed code and DocBlocks to comply with the PSR-2 Coding Standard.

    opened by pddevins 21
  • Include php-fpm binary

    Include php-fpm binary

    If PHP has been compiled with FPM, it would be nice to include the binary in the bin directory of the virtphp env, with the corresponding php-fpm.conf in the etc directory.

    opened by chadrien 18
  • Fix for Pearrc on OSX

    Fix for Pearrc on OSX

    This pull request fixes issues reported on these tickets:

    The issue is that when there was an existing .pearrc on OSX pear phar installation would fail, creating what looked like an empty /share/php folder which should have all of Pear folders.

    The solution is to move the .pearrc file during Pear's installation and then moving it back when done.

    This has been tested on OSX and Linux.

    opened by jwoodcock 16
  • Activate Command

    Activate Command

    Here is the activate command that when used:

    virtphp activate {envName}

    will pull the source path and try to copy to machine clipboard, OSX and Linux, and output the source path just in case the user did not have a compatible clipboard so they can copy and paste it in.

    Full test coverage as well.

    opened by jwoodcock 15
  • Set $COMPOSER_HOME into the virtphp env path

    Set $COMPOSER_HOME into the virtphp env path

    Setting $COMPOSER_HOME to $VIRTPHP_ENV_PATH/.composer, it would make all composer global xxx be executed in the virtphp env path, instead of user's $HOME.

    opened by chadrien 15
  • Option to activate env using virtphp

    Option to activate env using virtphp

    It would be great to have an option to activate the env using something like this:

    virtphp activate EpisodeIV

    opened by InFog 13
  • Functionality for show command

    Functionality for show command

    This PR holds new worker for handling the show functionality with tests which looks/writes to a file at the ~/{user directory}/.virtphp/environments.json.

    It also updates create, clone and destroy to insure the environments.json file is kept in sync depending on which action the user takes.

    Test are included and have been updated to cover the new functionality.

    opened by jwoodcock 13
  • Call to undefined function Virtphp\Util\json_decode()

    Call to undefined function Virtphp\Util\json_decode()

    As a new user to PHP, I installed the .51 alpha to create a new environment in my home folder. The virtphp.phar file has been given executable power within /usr/local/bin and runs.

    I attempted to run virtphp.phar create hanker but rec'd the following error:

    Fatal error: Call to undefined function Virtphp\Util\json_decode() in phar:///usr/local/bin/virtphp.phar/src/Virtphp/Util/EnvironmentFile.php on line 43

    Looking at this file it appears some environment vars should have been set up when this instance was created? I'm sure it's my ignorance but I didn't see this in the open/closed issues? What am I overlooking? thx, sam

    opened by sam452 12
  • Pear issue on Create

    Pear issue on Create

    When I run create, everything runs fine until it gets to pear and I get this error: [Symfony\Component\Filesystem\Exception\IOException] Cannot rename "/Users/Kite/work/virtphp/newenv/bin/pear" to "/Users/Kite/work/virtphp/newenv/bin/pear.pear".

    The status messages I get before this are:

    Checking current environment Creating directory structure Creating VirtPHP version file Creating custom php.ini Wrapping PHP binary Copying other libraries Downloading pear phar file, this could take a while... Installing PEAR

    This is the same issue Phil Sturgeon reported getting.

    Now, this is from within the project and not from a phar file.

    opened by jwoodcock 9
  • Should we archive this project?

    Should we archive this project?

    We're obviously not maintaining it actively... should we let other people know by marking it as "archived" in GitHub? People could still fork it and continue on if they want...

    opened by jakerella 1
  • Add support for extensions not hosted by PECL, such as Phalcon

    Add support for extensions not hosted by PECL, such as Phalcon

    As you may know, Phalcon isn't hosted by PECL, so I can't use pecl install after setting up a new virtual environment. On the other hand, PHPBrew provides an easy way to install these kind of extensions:

    $ phpbrew ext install

    But if I do this, the new extension isn't seen by my virtual environment, because it's installed inside the PHPBrew directory tree (and shims), not inside the VirtPHP ones.

    Now, I obviously could install Phalcon globally, and only after that create a new virtual environment, copying the current setup (extensions included), but this kind of defeats the purpose of a tool like VirtPHP: it would be better if I could install Phalcon only on those projects that actually use that framework (and without much hassle, I mean).

    So, is it possible to add a functionality like the one available in PHPBrew, to install extensions not belonging to PECL?

    Thank you very much!

    opened by michelezamuner 3
  • timezone settings on compile process

    timezone settings on compile process

    i was trying to build the project but i got this

    Failed to compile phar: [Exception] DateTime::__construct(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. at /path/to/cloned/repos/virtphp/src/Virtphp/Compiler.php:58%

    the output of the $process->getOutput(); is 2015-05-07 08:29:54 -0300

    opened by ramonmoraes8080 0
  • composer based env

    composer based env

    Afaik the composer library/module is for php what pip is for python? If it is there is just one problem: composer keeps binaries on an exclusive bin folder.

    So i kinda think: maybe my problem is to get a virtualenv for composer itself and not php at all, because the bin from composer are not linked over the bin folder from the virtphp which is the "goal" (for me) to use env.

    I think it could be a nice catch to set the VIRTPHP_ENV_PATH with the composer/bin path on the activate file.

    • update

    i've tried to manipulate the (environment variables)[] but notthing changed at the installation level. the only progress was to set the VIRTPHP_ENV_PATH to cover the original vendo folder.

    opened by ramonmoraes8080 0
  • Update Virtphp.php

    Update Virtphp.php

    now it can match hidden folder names :3

    opened by ramonmoraes8080 6
  • create env with hidden folder

    create env with hidden folder

    why is not possible to create env folder like: virtphp create .env. It's really helpful because it automatically fits under the default .gitignore configuration to dot folders. :)


    why the default --install-path is to a folder at the user's home? i think it's more useful to make it use the current path.

    opened by ramonmoraes8080 2
  • Add a Gitter chat badge to

    Add a Gitter chat badge to

    virtphp/virtphp now has a Chat Room on Gitter

    @ramsey has just created a chat room. You can visit it here:

    This pull-request adds this badge to your


    If my aim is a little off, please let me know.

    Happy chatting.

    PS: Click here if you would prefer not to receive automatic pull-requests from Gitter in future.

    opened by gitter-badger 1
  • Conflicts with Python virtualenv due to same name of environment variable

    Conflicts with Python virtualenv due to same name of environment variable

    $ source .virtphp/envs/php5/bin/activate You are currently running a virtualenv session: /home/username/local/python/3 Please exit this session before starting a virtPHP session.

    It looks like it's because it searches for this env variable in the actuvate scriptL if [ "$VIRTUAL_ENV" ] ; then

    Changing that to PHP_VIRTUAL_ENV seems to have fixed the problem, did a quick look and didn't find that used anywhere else.

    opened by djbclark 11
  • Sturgeon Holmes: The Case of the Missing pearcmd.php

    Sturgeon Holmes: The Case of the Missing pearcmd.php

    So I've spent the last 5 hours trying to make PECL work, which of course means getting PEAR to work.

    The trouble I'm having, is that in my little phpbrew + virtphp + OS X Mavericks world, the install-pear-nozlib.phar command is not doing what seems to be expected of it.

    It's not making either of the following files:

    • ~/.virtphp/envs/foo-env/share/php/pearcmd.php
    • ~/.virtphp/envs/foo-env/share/php/peclcmd.php

    This apparently does not happen on Linux, but on OSX it is happening for me over and over again.

    (foo-env) $ which pear
    (foo-env) $ pear
    Could not open input file: /Users/phil/.virtphp/envs/foo-env/share/php/pearcmd.php

    I open this issue to document the discoveries, but right now all I have is...


    The phar initiated in the Creator worker is just not making them files, and nobody seems to know why. The full command is:

    /Users/phil/.phpbrew/php/php-5.5.17/bin/php -n -dshort_open_tag=0 -dopen_basedir= -derror_reporting=1803 -dmemory_limit=-1 -ddetect_unicode=0 /Users/phil/.virtphp/envs/foo-env/share/install-pear-nozlib.phar -d "/Users/phil/.virtphp/envs/foo-env/share/php" -b "bin" -c "etc"

    We're expecting the files to appear in /Users/phil/.virtphp/envs/foo-env/share/php.

    Help me. I can't get an article finished until this actually works and im onto the last paragraph. I want to escape this hell and never think about PEAR again.

    I have suggested a template-based approach to add those two files, but @ramsey seems concerned that other files are also not being added, which sounds scary.

    opened by philsturgeon 11
  • v0.5.2-alpha(Jan 18, 2015)

    0.5.2-alpha (2015-1-18)

    Introduced the activate command which returns the source command to copy in order to activate an env, and if the system has a supported clipboard, copies the command to said clipboard

    Usage: virtphp activate {env_name}

    Source code(tar.gz)
    Source code(zip)
    virtphp.phar(367.06 KB)
  • v0.5.1-alpha(Aug 13, 2014)

  • v0.5.0-alpha(Jun 6, 2014)

  • v0.4.0-alpha(May 14, 2014)

    • Changed the default behavior of the create command to create all new virtPHP environments in ~/.virtphp/envs/; this may be overridden with the --install-path option
    • Added ability to delete a virtPHP environment by name with delete envname
    • Fixed issue in which we failed to remove an environment from the environments list
    • Updated all code in the project to conform to PSR-2 standard
    • Various improvements to tests and raised level of code coverage
    • Various bug fixes and docs improvements
    Source code(tar.gz)
    Source code(zip)
    virtphp.phar(351.16 KB)
  • v0.3.0-alpha(Mar 24, 2014)

    • Added show command to show all environments created with virtphp
    • Updated create, clone, and destroy commands to write to ~/.virtphp/environments.json when creating or destroying virtphp environments
    • Improved searching for a local ~/.pearrc config file (fixes #25)
    • Various bug fixes and docs improvements
    Source code(tar.gz)
    Source code(zip)
    virtphp.phar(345.63 KB)
  • v0.2.0-alpha(Mar 7, 2014)

    • Added checks to the activate script to detect whether another virtphp or virtualenv environment is running; one must deactivate virtualenv environments before they can activate a virtphp env. Switching virtphp env is allowed.
    • Added Travis CI and configuration to run tests and generate coverage reports
    • Changed to use PSR-4 autoloading
    • Typo fixes and documentation updates
    Source code(tar.gz)
    Source code(zip)
    virtphp.phar(338.60 KB)
  • v0.1.0-alpha(Mar 3, 2014)

🔰 Instant PHP quality checks from your console

PHP Insights was carefully crafted to simplify the analysis of your code directly from your terminal, and is the perfect starting point to analyze the code quality of your PHP projects.

Nuno Maduro 4.3k Jul 19, 2021
Brew & manage PHP versions in pure PHP at HOME

PHPBrew Read this in other languages: English, Português - BR, 日本語, 中文. phpbrew builds and installs multiple version php(s) in your $HOME directory. W

PHPBrew 4.7k Jul 25, 2021
Simple PHP version management

phpenv - PHP multi-version installation and management for humans. Key features: My name is phpenv. I was designed for humans, to help simplify the ma

php multiple release management 4 humans 1.1k Jul 22, 2021
Builds PHP so that multiple versions can be used side by side.

php-build php-build is a utility for building versions of PHP to use them side by side with each other. The overall structure is loosly borrowed from

php-build 905 Jul 8, 2021
Thin Wrapper around rbenv for PHP version managment

phpenv ![Gitter]( Chat.svg) Sets up a separate rbenv environment for PHP man page SYNOPSIS UPDATE=yes p

Christoph Hochstrasser 572 Jul 8, 2021