Phive: Secure, Easy, and Contained Phar Manager

Published On2021-07-28

Phive - Secure, Easy, and Contained Phar installer
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.

For example, 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.


What is Phive

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.

Phive vs Composer

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.

First-time Phive Setup

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

The last 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 PATH variable.

Using Phive

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 ~/.phive.

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.

Phive - GPG trust prompt

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 ~/.phive location.

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.

Phive - Call the Phar file

Installing an aliased Phar

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 squizlabs/php_codesniffer.

The complete list of aliases are available here.

To install a known aliased Phar, type its name with phive install:

phive install phpunit

Installing a Phar from a GitHub project

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

Installing a Phar from a direct URL

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

Installing a Phar file and copying it

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

Installing a specific version/constraint

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 phploc@6.0.2

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 Phar files

Updating all Phar archives in the current working directory takes just one step:

phive update

Phive looks up its configuration file for the version constraints, and if it allowed, and an update is available, Phive updates to that version.

Similar to composer update command, Phive also provides a command to list outdated Phar archives:

phive outdated

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 purge

phive.xml Configuration file

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/phars.xml.

If a 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/phars.xml to phive.xml.

Using Alongside Composer

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

Running phive composer prompts to install Phar archives of dependencies listed in the composer.json file. For each Phar installed, Phive also updates the phive.xml file.

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 .phive directory.

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 export-ignore

Recent Articles on PHP.Watch

All ArticlesFeed
Compressed HTTP Requests with Curl and PHP

Compressed HTTP Requests with Curl and PHP

How to make fast and efficient HTTP(S) requests via Curl using transfer encodings such as gzip, zstd, Brotli, and deflate.
How to compile PHP from source on Fedora/RHEL/etc

How to compile PHP from source on Fedora/RHEL/etc

A comprehensive guide on how to compile PHP from source on Fedora, RHEL, CentOS, etc. operating systems.
Directory Uploads in PHP 8.1

Directory Uploads in PHP 8.1

With PHP 8.1, it is possible to upload an entire folder from the browser using the `webkitdirectory` attribute.
Subscribe to PHP.Watch newsletter for monthly updates

You will receive an email on last Wednesday of every month and on major PHP releases with new articles related to PHP, upcoming changes, new features and what's changing in the language. No marketing emails, no selling of your contacts, no click-tracking, and one-click instant unsubscribe from any email you receive.