Phive: Secure, Easy, and Contained Phar Manager
Composer supports installing PHP tools such as PHPUnit, PHP CS Fixer, PHPStan, and Phan if they are declared as dependencies in the
composer.json file. Composer does not support installing multiple versions of the same library, and the dependencies of these tools can cause conflicts with the dependencies of the application, or dependencies of other tools.
phpDocumentor version 3 depends on the version 5.x series of
symfony/console library. If there are any other tool that requires an incompatible version of the
symfony/console library, Composer refuses to complete installation because it is impossible to find a suitable version that matches all version constraints.
PHP supports creating a self-contained executable archives, commonly known as Phar archives. One of the easiest ways to avoid version conflicts when installing PHP tools is to use the Phar versions of the tools. The Phar file contains a copy of all dependencies, and do not cause conflicts with the application itself or other Phar archives.
Phive is a PHP tool, that can be used to install, update, and validate Phar archives easily. Phive saves the hassle of finding the Phar file URLs, downloading them, changing their permissions, and making them to ready to use within the applications.
Further, Phive validates the GPG signatures of Phar archives by default. This avoids supply-chain attacks, and makes it very convenient to do so. Let's be real - it is very unlikely that one would lookup the authors GPG keys, download them off a keyserver, and manually validate their signatures. Phive does this by default for all supported Phar archives.
Phive also provides support a custom
phive.xml configuration file to declare the Phive files and their version constraints. With a
phive.xml file, it is easy to share the tooling setup of any PHP application with others.
Developed by Arne Blankerts, Sebastian Heuer, and dozens of other brilliant minds, Phive can help in development environments, CI/CD setups, etc. to quickly setup all the tools required for a PHP project.
Composer and Phive are similar in the sense that they both are dependency managers.
Composer provides autoloading capabilities, custom repositories, and more features. Phive, on the other hand, has a very focused use-case. It is meant to be used as a tool to download and install other Phar archives. It supports installing Phar extensions from an arbitrary URL, but its usual use case installing a smaller set well-known and aliased PHP tools such as PHPUnit, PHPLoC, PHP CS Fixer, etc.
Unlike Composer, Phive provides built-in GPG integration to validate the signature of the Phars being downloaded. Composer can validate Composer itself during an upgrade, but it does not validate the downloaded packages against the authors known GPG keys.
Phive can be used alongside Composer, that dependencies set in the
composer.json can be moved to a new
phive.xml configuration file. This can reduce potential dependency conflicts at Composer installations.
Phive itself is distributed as a Phar archive. In order for PHP to run Phar files, PHP must be compiled with Phar support; this is enabled by default. Further, it requires
gpg setup in the computer.
Latest installation instructions are available at the Phar web site, but here is a quick summary:
wget -O phive.phar https://phar.io/releases/phive.phar wget -O phive.phar.asc https://phar.io/releases/phive.phar.asc gpg --keyserver hkps://keys.openpgp.org --recv-keys 0x9D8A98B29B2D5D79 gpg --verify phive.phar.asc phive.phar chmod +x phive.phar sudo mv phive.phar /usr/local/bin/phive
mv call moves the downloaded and validated
phive.phar file to
/usr/local/bin/phive location, which allows calling
phive from any directory.
On Windows, make sure to move the downloaded
phive.phar file location to Windows
Once Phive is installed, all Phive can be invoked with the
phive command. Running
phive commands do not require sudo/administrator privileges because its default location to store actual Phive archives is
As soon as Phive downloads a Phar file, it attempts to fetch its signature file. If the file is signed by a trusted GPG key, the Phar file is installed in the project. First-time encounters of a GPG key is downloaded from a GPG keyserver, and prompted to trust the key.
Once the GPG validation passed, the Phar archive is saved to
~/.phive directory (by default), and a symlink is created at
tools directory to the
For example, installing
phpunit results in Phive saving the PHPUnit Phar file to
~/.phive directory, and then symlinked from
tools/phpunit in the current directory.
To use the downloaded Phar, invoke it from the
./tools sub directory.
The main use case of Phive is installing a PHP tool. Phive has a pre-configured repository that it tries to lookup a PHP tool by its name. For example,
phpunit is aliased to
phpunit/phpunit package, and
phpcbf is aliased to
The complete list of aliases are available here.
To install a known aliased Phar, type its name with
phive install phpunit
Phive can also download, validate, and install a Phar file from a GitHub project name. Phive looks up releases under a given GitHub project, and picks the Phar file under its assets.
Note that not all projects publish Phar archives and their signatures. The
theseer/Autoload project, for example, publishes releases as Phar archives, along with their signature files (
.phar.asc files), and Phive can do its magic just from the GitHub project name.
phive install Autoload/releases
Phive can download and install a Phar file directly from a URL as well. Phive attempts to fetch the signature file by appending
.asc to the URL.
phive install https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.1.0/phpDocumentor.phar
By default, Phar files are symlinked to its cached location. This saves disk space and makes setting up cached tools almost instantaneous.
To copy the Phar file instead of linking to it, add
--copy flag to any of the
phive install commands:
phive install phploc --copy
Phive picks the latest version of the given project by default. However, it is possible to specify a specific version or version constraint as well.
phive install email@example.com
Calling above installs
phploc project in version
6.0.2. Phive does not attempt to update
phploc because it is installed with a specific version.
phive install phploc@~6.0.0
The example above is when a Phar archive is installed with a version constraint.
phploc@~6.0.0 means that Phive is allowed to pick the latest version in
6.0.X series, and update
phploc in the event there is a new version in the series.
Updating all Phar archives in the current working directory takes just one step:
Phive looks up its configuration file for the version constraints, and if it allowed, and an update is available, Phive updates to that version.
composer update command, Phive also provides a command to list outdated Phar archives:
Removing a Phar file
phive remove phploc
If the installation target is merely a symlink, only the symlink is removed.
Phive shows a message if the Phar archive removed is no longer used in any other project, and calling
phive purge removes the downloaded Phar file from the cache.
Phive can make use of a
phive.xml configuration file to store a list of Phar archives along with their version information. Just like a
composer.json file declares the dependencies, a
phive.xml file can keep a list of Phar archives for a given project.
By default, Phive does not create a
phive.xml file when it is used on a directory for the first time. Instead, it creates and maintains
phive.xml file is present in the current working directory, Phive maintains the
phive.xml file which lists the Phar archives for the current project. The
.phive/phars.xml file follows the same definitions as
phive.xml file, which can be moved from
Phive can also read a
composer.json file and install known Phar archives. It does not remove the entries from the
composer.json file, nor update the
composer.lock lock file.
phive composer prompts to install Phar archives of dependencies listed in the
composer.json file. For each Phar installed, Phive also updates the
Working with Version Controlling Systems
Phar archives are compressed binary files, and do not play well with version controlling systems. Phive uses symlinks to link to the actual Phar archive, and does not add any weight to the working directory of a project.
When working with a version controlling system such as Git, it makes more sense to use a
phive.xml file, and not remove the
Further, the Phar archive links are created in a
tools sub directory by default, which might be better if added to the
.gitignore file or the
.gitattributes file as