Phar Updater Laravel Package

Getting Started

Install the package via Composer (v2 requires PHP 8.3+):

composer require laravel-zero/phar-updater

v2.0.0 is a breaking release, so read the upgrade notes below before bumping an existing app. If you are already on 1.4.x and never used OpenSSL signing or SHA-1, the practical migration is usually: bump the constraint, confirm your build step signs with GPG, and re-run your self-update command in a scratch build.

Create a self-update command in your PHAR-based application (Laravel Zero’s app:update scaffolding or a hand-written command). The simplest usage assumes the currently running PHAR is the target. Instantiate Humbug\SelfUpdate\Updater and call $updater->update() inside the command, wrapping it in try/catch — failures typically mean a signature/hash mismatch, a blocked network call, or a PHP stream misconfiguration.

Implementation Patterns

• SHA-512 Strategy (new default)
  SHA-512 is now the default algorithm, aligning with Box. Point pharUrl() and versionUrl() at a version file whose first token is the hash, and regenerate it on every build:

  sha256sum app.phar > app.version   # or sha512sum, matching your configured algorithm
  

  SHA-256 remains supported; SHA-1 has been removed in v2. If you are still on STRATEGY_SHA1, migrate now — there is no fallback.

• GPG Signature Verification (replaces OpenSSL)
  OpenSSL signing is gone. Sign the built PHAR with your GPG key, ship the detached signature alongside the release, and register the public key with the updater so it verifies before replacing the binary. Bake the verification step into the same CI job that produces the PHAR so a signature can never drift from the artifact.

• 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 exactly
  

  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 mid-task.

• 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 a user-initiated command.

• Custom Strategies (strict types)
  Implement Humbug\SelfUpdate\Strategy\StrategyInterface for bespoke logic (internal artifact repos, custom metadata APIs). v2 adds declare(strict_types=1) across the codebase, so your implementations must match the interface signatures exactly — typed params and return types included. Wire it in with setStrategyObject() — not setStrategy().

Gotchas and Tips

• v1 → v2 upgrade checklist: (1) remove any OpenSSL signing code and .phar.pubkey handling; (2) move off STRATEGY_SHA1; (3) bump CI to PHP 8.3+; (4) update custom strategy signatures for strict types. Any of these silently left in place will fail at runtime, not at install time.

• Changing signing keys: With OpenSSL gone, GPG key rotation is now the path. A user who has already installed a PHAR trusting an old key still needs a manual reinstallation to pick up the new one — the updater cannot bootstrap trust in a new key.

• 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 the remote tag exactly. Use a consistent prefix (e.g., v1.0.0) and avoid hyphens/underscores unless mirrored on GitHub.

• 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. Verify the algorithm too: a SHA-256 hash checked against a strategy configured for SHA-512 produces the same class of error.

• Test the unsigned path deliberately: With SHA-1 and OpenSSL gone, a misconfigured build that produces no GPG signature should fail loudly. Add a CI check that runs the self-update command against a throwaway release before you tag a real one — this is the cheapest way to catch a broken signing step.