Manifest file strategy (updated)

README.md

@@ -13,16 +13,18 @@ minions (all ten of them) have written one for you.
 - [Introduction](#introduction)
 - [Installation](#installation)
 - [Usage](#usage)
+    - [Constructor Parameters](#constructor-parameters)
     - [Basic SHA-1 Strategy](#basic-sha-1-strategy)
     - [Github Release Strategy](#github-release-strategy)
+    - [Manifest Strategy](#manifest-strategy)
     - [Rollback Support](#rollback-support)
-    - [Constructor Parameters](#constructor-parameters)
     - [Check For Updates](#check-for-updates)
     - [Avoid Post Update File Includes](#avoid-post-update-file-includes)
     - [Custom Update Strategies](#custom-update-strategies)
 - [Update Strategies](#update-strategies)
     - [SHA-1 Hash Synchronisation](sha-1-hash-synchronisation)
     - [Github Releases](#github-releases)
+    - [Manifest Files](#manifest-files)
 
 Introduction
 ============
@@ -49,6 +51,7 @@ The package utilises PHP Streams for remote requests so it will require the open
 extension and the `allow_url_open` setting to both be enabled. Support for curl
 will follow in time.
 
+
 Usage
 =====
 
@@ -57,6 +60,41 @@ version file, and will update the local phar when this version is changed. There
 is also a Github strategy which tracks Github Releases where you can upload a
 new phar file for a release.
 
+Please bear in mind the constructor parameters which primarily determine what
+strategy to use, and whether PHARs are signed.
+
+### Constructor Parameters
+
+The Updater constructor is fairly simple. The three basic variations are:
+
+```php
+/**
+ * Default: Update currently running phar which has been signed.
+ */
+$updater = new Updater;
+```
+
+```php
+/**
+ * Update currently running phar which has NOT been signed.
+ */
+$updater = new Updater(null, false);
+```
+
+```php
+/**
+ * Use a strategy other than the default SHA Hash.
+ */
+$updater = new Updater(null, false, Updater::STRATEGY_GITHUB);
+```
+
+```php
+/**
+ * Update a different phar which has NOT been signed.
+ */
+$updater = new Updater('/path/to/impersonatephil.phar', false);
+```
+
 ### Basic SHA-1 Strategy
 
 Create your self-update command, or even an update command for some other phar
@@ -154,7 +192,7 @@ $updater = new Updater();
 $updater->setStrategy(Updater::STRATEGY_GITHUB);
 $updater->getStrategy()->setPackageName('myvendor/myapp');
 $updater->getStrategy()->setPharName('myapp.phar');
-$updater->getStrategy()->setCurrentLocalVersion('v1.0.1');
+$updater->getStrategy()->setCurrentLocalVersion('1.0.1');
 try {
     $result = $updater->update();
     echo $result ? "Updated!\n" : "No update needed!\n";
@@ -188,6 +226,77 @@ If you want to ignore stability and just update to the most recent version regar
 $updater->getStrategy()->setStability('any');
 ```
 
+### Manifest Strategy
+
+The Manifest Strategy uses a manifest file stored remotely to determine available
+versions and download URLs. Signed files are currently not supported. You can
+read an overview of the manifest file format here: [Manifest Files](#manifest-files).
+
+```php
+/**
+ * Other than somewhat different setters for the strategy, all other operations
+ * are identical.
+ */
+
+use Humbug\SelfUpdate\Updater;
+
+$updater = new Updater(null, false);
+$updater->setStrategy(Updater::STRATEGY_MANIFEST);
+$updater->getStrategy()->setManifestUrl('http://www.example.com/manifest.json');
+$updater->getStrategy()->setCurrentLocalVersion('1.0.1');
+try {
+    $result = $updater->update();
+    echo $result ? "Updated!\n" : "No update needed!\n";
+} catch (\Exception $e) {
+    echo 'Well, something happened! Either an oopsie or something involving hackers.\n";
+    exit(1);
+}
+```
+
+The Manifest Strategy is more flexible than most strategies since you can define
+more relevant metadata. For example, here's an extended example which shows a
+fuller range of optional update controls and information for users.
+
+```php
+use Humbug\SelfUpdate\Updater;
+
+$updater = new Updater(null, false);
+$updater->setStrategy(Updater::STRATEGY_MANIFEST);
+$updater->getStrategy()->setManifestUrl('http://www.example.com/manifest.json');
+$updater->getStrategy()->setCurrentLocalVersion('1.0.1');
+
+/**
+ * 1) Allow updates outside of the current major version installed locally.
+ * 2) Allow updates even if local PHP version is not within PHP requirements per manifest.
+ * 3) Allow updates to an unstable version (e.g. beta). 'stable' and 'unstable' or
+ *    their corresponding constants are alternatives.
+ * 4) If they exist, display update notes from manifest file to user.
+ * 5) (Not recommended!) Use SHA-1 instead of SHA-256
+ */
+$update->getStrategy()
+    ->allowMajorVersionUpdates()
+    ->ignorePhpRequirements()
+    ->setStability('any')
+    ->useSha1();
+
+try {
+    $result = $updater->update();
+    echo $result ? "Updated!\n" : "No update needed!\n";
+
+    /**
+     * We pass in the Updater, i.e. can be used without actually
+     * updating, for example when checking for updates.
+     */
+    $updateNotes = $update->getStrategy()->getUpdateNotes($updater, true);
+    if (false !== $updateNotes) {
+        echo($updateNotes . "\n");
+    }
+} catch (\Exception $e) {
+    echo 'Well, something happened! Either an oopsie or something involving hackers.\n";
+    exit(1);
+}
+```
+
 ### Rollback Support
 
 The Updater automatically copies a backup of the original phar to myname-old.phar.
@@ -219,37 +328,6 @@ from using the `setBackupPath()` function when updating a current phar or the
 `setRestorePath()` prior to triggering a rollback. These will be used instead
 of the simple built in convention.
 
-### Constructor Parameters
-
-The Updater constructor is fairly simple. The three basic variations are:
-
-```php
-/**
- * Default: Update currently running phar which has been signed.
- */
-$updater = new Updater;
-```
-
-```php
-/**
- * Update currently running phar which has NOT been signed.
- */
-$updater = new Updater(null, false);
-```
-
-```php
-/**
- * Use a strategy other than the default SHA Hash.
- */
-$updater = new Updater(null, false, Updater::STRATEGY_GITHUB);
-```
-
-```php
-/**
- * Update a different phar which has NOT been signed.
- */
-$updater = new Updater('/path/to/impersonatephil.phar', false);
-```
 
 ### Check For Updates
 
@@ -322,15 +400,15 @@ $updater->setStrategyObject(new MyStrategy);
 ```
 
 The similar `setStrategy()` method is solely used to pass flags matching internal
-strategies.
+strategies, e.g. `\Humbug\SelfUpdater\Updater::STRATEGY_MANIFEST`.
 
 Update Strategies
 =================
 
 SHA-1 Hash Synchronisation
 --------------------------
 
-The phar-updater package only (that will change!) supports an update strategy
+The phar-updater package only supports an update strategy
 where phars are updated according to the SHA-1 hash of the current phar file
 available remotely. This assumes the existence of only two to three remote files:
 
@@ -390,3 +468,71 @@ you create a new git tag. If you use git tagging, you can go to the matching
 release on Github, click the `Edit` button and attach files. It's recommended to
 do this as soon as possible after tagging to limit the window whereby a new
 release exists without an updated phar attached.
+
+Manifest Files
+--------------
+
+A manifest is basically a list of versions available from a remote endpoint,
+optionally containing additional metadata. The format supported by the built-in
+Manifest Strategy is a JSON file. Here's the simplest set of entries supported.
+
+```js
+[
+  {
+    "sha256": "edb9a27795c1ec15e5c23d6cda1cc0ed0242b296f27ed0f39ae7eb4784a93744",
+    "url": "http://www.example.com/1.2.0/scrabble.phar",
+    "version": "1.2.0"
+  },
+  {
+    "sha256": "054e0cead9afd277865537ccb29586e546b2ccc5fc9d5ddfc401ee0ec36b1808",
+    "url": "http://www.example.com/1.1.0/scrabble.phar",
+    "version": "1.1.0"
+  }
+]
+```
+Your download URLs could easily be files hosted in a Github Release, with the
+manifest uploaded to a github.io site.
+
+You can include optional manifest metadata specifying a minimum PHP version,
+release notes, and version bounded notes (shown only to a range of versions
+being updated from). Here's add optional metadata when updating to `1.2.0`
+include a minimum PHP vesion supported (a maximum is also possible), a release note,
+and a note for anyone updating from `1.1.10` but not if updating from `1.1.12` or later.
+
+```js
+[
+  {
+    "sha256": "edb9a27795c1ec15e5c23d6cda1cc0ed0242b296f27ed0f39ae7eb4784a93744",
+    "url": "http://www.example.com/1.2.0/scrabble.phar",
+    "version": "1.2.0"
+    "php": {
+      "min": "7.1",
+      "max": "7.2"
+    },
+    "notes": "This is a version note or changelog",
+    "updating": [
+      {
+        "notes": "Specific note (ignores earlier notes) to display for certain versions",
+        "show from": "1.1.10",
+        "hide from": "1.1.12"
+      }
+    ]
+  },
+  {
+    "sha256": "054e0cead9afd277865537ccb29586e546b2ccc5fc9d5ddfc401ee0ec36b1808",
+    "url": "http://www.example.com/1.1.0/scrabble.phar",
+    "version": "1.1.0"
+  }
+]
+```
+
+Notes can be retrieved from the Manifest strategy object using the `getUpdateNotes()`
+method.
+The PHP constraints are applied, when defined in the manifest, and if you
+have not called the strategy object's `ignorePhpRequirements()` method to disable
+those restrictions.
+
+SHA-256 with the `sha256` entry is strongly recommended. If you need to support
+SHA-1 file hashes, and cannot transition immediately, you may use SHA-1 using
+a `sha1` entry instead. You must then call the `useSha1()` method on the strategy
+object to enable SHA-1 support.

src/Strategy/GithubStrategy.php

@@ -76,7 +76,12 @@ public function download(Updater $updater)
             ));
         }
 
-        file_put_contents($updater->getTempPharFile(), $result);
+        $result = file_put_contents($updater->getTempPharFile(), $result);
+        if (false === $result) {
+            throw new RuntimeException(
+                sprintf('Failed to write file: %s', $updater->getTempPharFile())
+            );
+        }
     }
 
     /**