Getting Started

Start by requiring the package via Composer:

composer require padraic/phar-updater

Since the package is archived and hasn’t seen updates since 2018, verify compatibility with modern PHP versions (≥7.1) before use. The core use case is enabling self-updating CLI PHAR tools, so initial integration involves embedding the updater inside your PHAR’s entry point (e.g., bin/console or my-tool.phar).

Basic first use:

use Padraic\PharUpdater\Updater;

$updater = new Updater('https://example.com/manifest.json', '/path/to/my-tool.phar');
$update  = $updater->getUpdate();

if ($update) {
    $updater->update(); // Downloads, verifies, and replaces PHAR
}

Manifest files should be JSON and include at minimum: version, url, and signature (see docs/manifest-example.json in repo). Begin with simple HTTPs hosting (e.g., GitHub Releases or custom server).

Implementation Patterns

1. Self-Updating PHAR Workflow

Wrap the updater in your PHAR’s bootstrap or CLI command (e.g., self-update). Keep logic minimal:

if ($input->getArgument('command') === 'self-update') {
    $updater = new Updater('https://cdn.example.com/manifest.json', Phar::running(false));
    $update  = $updater->getUpdate();
    if ($update && $updater->update()) {
        output("Updated to v{$update->getVersion()}");
    } else {
        output("Already up-to-date.");
    }
    exit;
}

2. Verifying Signatures

Integrate OpenSSL verification to ensure authenticity:

$pubKey = file_get_contents(__DIR__ . '/keys/public.pem');
$updater->setPublicKey($pubKey);
$updater->setSignatureAlgorithm(Updater::SIGNATURE_SHA256); // or custom

Manifest should include signature field with base64-encoded signature of the PHAR file (e.g., openssl_digest($pharContents, 'sha256')).

3. Atomic Replacement via Temporary File

The package uses atomic replacement under the hood (write new PHAR to temp, rename on success). Do not manually overwrite the running PHAR—trust the updater’s logic to prevent corruption.

4. Custom HTTP Handlers

For advanced networks (e.g., private repos with auth), inject a custom Guzzle client:

$client = new GuzzleHttp\Client(['headers' => ['Authorization' => 'Bearer ...']]);
$updater->setHttpClient($client);

Gotchas and Tips

⚠️ Manifest Format Is Critical

The JSON manifest must be valid and include url, version, and signature. A typo (e.g., missing quotes, trailing commas) will break parsing silently. Validate manifests with json_decode() before deployment.

⚠️ Permissions and PHAR Execution

phar.readonly=0 must be set in php.ini to allow PHAR modification (dangerous in production web contexts, but safe for CLI tools). Document this requirement.

⚠️ Rollback Limitations

While the updater avoids partial writes, it does not auto-rollback on runtime failures post-update (e.g., new PHAR crashes on execution). Consider storing the previous PHAR version’s checksum/path in a .prev file for manual recovery.

🔧 Extension Points

Extend Updater to override verifySignature() for custom schemes (e.g., GPG).
Override download() for proxies, rate-limiting, or offline fallback.

🐛 Debugging Tip

Enable verbose output by catching exceptions:

try {
    $updater->update();
} catch (\Exception $e) {
    fwrite(STDERR, "Update failed: {$e->getMessage()}\n");
    // Log $e->getTraceAsString() for deeper insight
}

💡 Security Best Practice

Never fetch manifests over HTTP. Always use HTTPS, and pin certificates or use known CA bundles. In CI/CD pipelines, validate signatures before packaging the PHAR.

📦 Maintenance Warning

Given the last release was in 2018, ensure the library works with modern PHP versions (tested up to 7.4, but may break on 8.x due to deprecations). Consider vendoring a patched fork or migrating to more active alternatives like clue/phar-update or heredoc/box if security is critical.

Phar Updater Laravel Package