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.
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/phiveThe 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.
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.
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 phpunitInstalling 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/releasesInstalling 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.pharInstalling 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 --copyInstalling 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.2Calling 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.0The 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 updatePhive 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 outdatedRemoving a Phar file
phive remove phplocIf 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 purgephive.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 composerRunning 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
