Phar Update Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require herrera-io/phar-update:1.*
   

   (Note: The package is archived, but version 1.* remains functional.)

2. Basic Usage: Create a manifest.json file (hosted publicly) with your Phar update metadata:

   {
       "version": "1.2.0",
       "url": "https://example.com/path/to/your.phar",
       "checksum": "sha256:abc123...",
       "require": ["php": ">=7.4"]
   }
   

   Load it in your Phar’s bootstrap:

   use Herrera\Phar\Update\Manager;
   $manager = new Manager(Manifest::loadFile('https://yourdomain.com/manifest.json'));
   

3. First Use Case: Check for updates and auto-update if available:

   $manager->update('1.0.0', true); // Auto-update if newer than 1.0.0
   

Implementation Patterns

Core Workflows

1. Version-Based Updates:

   • Use update($currentVersion, $autoUpdate) to trigger updates.
   • Pass true for $autoUpdate to silently replace the Phar if a newer version exists.

2. Pre-Update Hooks:

   • Extend Herrera\Phar\Update\Manifest to add custom validation:

     $manifest = new Manifest([
         'version' => '1.2.0',
         'url' => '...',
         'preUpdate' => function() {
             // Backup user data, log, etc.
         }
     ]);
     

3. Phar-Specific Integration:

   • Place the Manager in your Phar’s bootstrap (e.g., phar://your-app.phar/bootstrap.php).
   • Use Phar::running() to detect if the script is running from a Phar:

     if (Phar::running()) {
         $manager->update('1.0.0', true);
     }
     

4. Fallback Logic:

   • Handle failed updates gracefully:

     try {
         $manager->update('1.0.0', true);
     } catch (Exception $e) {
         error_log("Update failed: " . $e->getMessage());
         // Fallback to local cache or user prompt
     }
     

Advanced Patterns

• Custom Update Sources: Override Herrera\Phar\Update\Manifest::loadFile() to fetch manifests from private APIs or databases.

• Delta Updates: Combine with phar.io/phar to implement delta updates (e.g., only patch changed files).

• User Feedback: Use Manifest::setOptions(['verbose' => true]) to log update steps to stderr.

Gotchas and Tips

Pitfalls

1. Phar Permissions:

   • The update process requires write permissions to the Phar file’s directory.
   • Fix: Ensure the web server user (e.g., www-data) has write access:

     chown www-data:www-data /path/to/phar/
     chmod 755 /path/to/phar/
     

2. Manifest Validation:

   • Always validate the checksum field in manifest.json to prevent tampering.
   • Tip: Use hash_file('sha256', $pharPath) to verify the downloaded Phar.

3. Phar Signature:

   • If your Phar is signed (e.g., with phar.io/phar), the update will break the signature.
   • Workaround: Re-sign the Phar post-update using Phar::mapPhar().

4. PHP Version Mismatches:

   • The require field in the manifest is not enforced by this library.
   • Tip: Add runtime checks:

     if (version_compare(PHP_VERSION, '7.4') < 0) {
         throw new RuntimeException("PHP 7.4+ required");
     }
     

5. Archived Package:

   • No new releases are expected. Tip: Fork the repo if you need modifications.

Debugging

• Enable Verbose Mode:

  $manager->setOptions(['verbose' => true]);
  

  Logs will show:

  [DEBUG] Downloading manifest from https://example.com/manifest.json
  [DEBUG] Current version: 1.0.0, Available: 1.2.0
  [DEBUG] Downloading update from https://example.com/app.phar
  

• Check HTTP Errors: Use Manifest::loadFile() with a custom HTTP client (e.g., Guzzle) to debug 404/500 errors:

  $client = new \GuzzleHttp\Client();
  $manifest = Manifest::loadFile('https://...', $client);
  

Extension Points

1. Custom Manifest Sources: Implement Herrera\Phar\Update\ManifestSourceInterface for non-HTTP sources (e.g., S3, local files).

2. Post-Update Actions: Extend the Manager to run scripts after update:

   $manager->update('1.0.0', true, function() {
       // Clear cache, restart services, etc.
   });
   

3. Offline Updates: Cache manifests locally and use Manifest::loadArray() to avoid network calls:

   $manifestData = file_get_contents('cache/manifest.json');
   $manager = new Manager(Manifest::loadArray(json_decode($manifestData, true)));