virtphp
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.
Installation
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.
Usage
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:
user@host:~$ php virtphp.phar
If you have the phar file set executable (i.e. chmod 755), then you can execute it like this:
user@host:~$ ./virtphp.phar
Or, if it’s in your PATH, like this:
user@host:~$ virtphp.phar
We recommend putting it in your PATH and aliasing it to virtphp, so that you can run it like this:
user@host:~$ 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:
user@host:~$ 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:
user@host:~$ 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) user@host:~$
And, when you run which php, your shell session reports it is now using PHP from your virtPHP environment:
(myenv) user@host:~$ which php /home/user/myenv/bin/php
Now, let’s install a PECL extension and a PEAR package.
(myenv) user@host:~$ pecl install mongo (myenv) user@host:~$ pear config-set auto_discover 1 (myenv) user@host:~$ pear install pear.phpunit.de/PHPUnit
(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) user@host:~$ 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.
user@host:~$ 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.
user@host:~$ 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:
myenv/
|-- 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/
| `-- mongo.so
`-- 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 mongo.so), 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.
user@host:~$ php virtphp.phar create --php-bin-dir="/home/user/.phpbrew/php/php-5.4.25/bin" project1-env user@host:~$ 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:
user@host:~$ source project1-env/bin/activate # Activate project1 (project1-env) user@host:~$ pecl install mongo-1.2.12 (project1-env) user@host:~$ deactivate user@host:~$ source project2-env/bin/activate # Activate project2 (project2-env) user@host:~$ pecl install mongo-1.4.5 (project2-env) user@host:~$ 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.
user@host:~$ 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…