Phar Updater Laravel Package

Getting Started

Start by installing the package via Composer:

composer require laravel-zero/phar-updater

Then, configure a self-update command in your PHAR-based application (e.g., using Laravel Zero’s CLI tooling or manually). The simplest usage assumes the currently running PHAR is to be updated and is signed with OpenSSL. Create an instance of Humbug\SelfUpdate\Updater (alias via use if needed) and call $updater->update() within an artisan command. Handle exceptions carefully — failures often indicate security blocks (e.g., SSL verification failure) or network issues.

Implementation Patterns

• SHA-256 Strategy (Recommended)
  Use STRATEGY_SHA256 over deprecated STRATEGY_SHA1. Set pharUrl() and versionUrl() pointing to a version file (e.g., https://example.com/app.version) containing the hash as the first token. Regenerate this file on every build using sha256sum app.phar > app.version.

• GitHub Releases Strategy
  Ideal for stable releases:

  $updater->setStrategy(Updater::STRATEGY_GITHUB);
  $updater->getStrategy()
      ->setPackageName('vendor/app')
      ->setPharName('app.phar')
      ->setCurrentLocalVersion('v1.2.3'); // Must match GitHub tag
  

  Store the version string in your PHAR (e.g., compile-time injection) and manage release tags via GitHub UI or CLI.

• Update Check + Graceful UX
  Prefer hasUpdate() over blind update():

  if ($updater->hasUpdate()) {
      $new = $updater->getNewVersion();
      // Notify user, ask for confirmation, log, etc.
      if ($confirm && $updater->update()) {
          exit("Updated to $new — restarting...");
      }
  }
  

  This avoids unexpected interruption.

• Rollback Handling
  By default, backups are saved as {filename}-old.phar. Use setBackupPath() and setRestorePath() for custom paths, then call rollback() in error-handling logic or user-initiated commands.

Gotchas and Tips

• SSL/TLS & Stream Wrappers: The package relies on PHP streams, not cURL. Ensure openssl is enabled and allow_url_fopen=On in php.ini. Self-signed or misconfigured HTTPS endpoints will fail — test with php -r "file_get_contents('https://...')" first.

• Avoid "internal corruption" Errors: After replacing a running PHAR, in-memory class autoloading fails. Pre-load critical classes before $updater->update() or disable event dispatchers (e.g., Symfony’s) in your self-update command. Keep the update command minimal.

• Version String Consistency: With GitHub strategy, setCurrentLocalVersion() must match remote tag exactly. Use a consistent prefix (e.g., v1.0.0) and avoid hyphens/underscores unless mirrored on GitHub.

• Signing is Non-Negotiable for Security: Enable OpenSSL signing (phpscoper_phar->setSignatureAlgorithm(OpenSSLPKCS1::ALGO_SHA256)) and provide .phar.pubkey. Users must trust the local public key — changing keys requires manual reinstallation (not handled by updater).

• Debugging Tip: Wrap calls in try/catch and log $e->getMessage() — errors like "The hash of the PHAR does not match the one in the version file" are often due to trailing whitespace in .version files. Trim manually or use trim() in your generation script.

• Custom Strategies: Extend Humbug\SelfUpdate\Strategy\StrategyInterface for bespoke logic (e.g., internal artifact repos, custom metadata APIs). Pass it via setStrategyObject() — not setStrategy().