phar-site-generator

phar-site-generator is a tool that generates an HTML page (example), RSS feed (example), and Phive metadata (example) for a PHAR repository.

This tool makes the following assumptions:

• The PHAR repository is hosted using Apache HTTPD or nginx
• The PHAR repository is hosted using HTTPS
• The PHAR repository directory contains .phar (PHP Archive) and .phar.asc (GPG signature) files
• A .phar file may be accompanied by a .phar.cdx.xml file (Software Bill of Materials in CycloneDX format) and its .phar.cdx.xml.asc (GPG signature) file

Usage

We distribute a PHP Archive (PHAR) that has all required (as well as some optional) dependencies of phar-site-generator bundled in a single file:

wget https://phar.phpunit.de/phar-site-generator.phar

phar-site-generator requires an XML configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<phar-site>
    <domain>phar.phpunit.de</domain>
    <email>sebastian@phpunit.de</email>
    <directory>/webspace/phar.phpunit.de/html</directory>
    <nginx>/webspace/phpunit.de/phar/redirects.conf</nginx>
</phar-site>

The <nginx> element configures the file that the redirect configuration for nginx is written to.

When the PHAR repository is hosted using Apache HTTPD, use the <apache> element instead. It configures the file, for instance an .htaccess file in the PHAR repository directory, that the redirect configuration (as well as the MIME type configuration for .phar and .phar.asc files) for Apache HTTPD is written to:

<?xml version="1.0" encoding="UTF-8"?>
<phar-site>
    <domain>phar.phpunit.de</domain>
    <email>sebastian@phpunit.de</email>
    <directory>/webspace/phar.phpunit.de/html</directory>
    <apache>/webspace/phar.phpunit.de/html/.htaccess</apache>
</phar-site>

Both the <apache> and the <nginx> element are optional and can be used together.

A leading ~ in any of the configured paths is expanded to the home directory of the user that runs phar-site-generator.

The optional <cache> element configures a file in which the SHA-256 hashes of the .phar files are cached between runs:

<?xml version="1.0" encoding="UTF-8"?>
<phar-site>
    <domain>phar.phpunit.de</domain>
    <email>sebastian@phpunit.de</email>
    <directory>/webspace/phar.phpunit.de/html</directory>
    <nginx>/webspace/phpunit.de/phar/redirects.conf</nginx>
    <cache>/webspace/phpunit.de/phar/cache.json</cache>
</phar-site>

Without a cache, every .phar file is read and hashed on every run. With a cache, only .phar files that were not seen before, or whose size or modification time changed, are hashed. The cache file should not be located in the PHAR repository directory and should not be shared between configurations. When the cache file cannot be written, phar-site-generator reports an error and exits with exit code 1.