Allow disabling updates across major versions with Github strategy

README.md

@@ -155,6 +155,7 @@ $updater->setStrategy(Updater::STRATEGY_GITHUB);
 $updater->getStrategy()->setPackageName('myvendor/myapp');
 $updater->getStrategy()->setPharName('myapp.phar');
 $updater->getStrategy()->setCurrentLocalVersion('v1.0.1');
+$updater->getStrategy()->blockMajorVersionUpdates();
 try {
     $result = $updater->update();
     echo $result ? "Updated!\n" : "No update needed!\n";
@@ -173,6 +174,11 @@ the version string used by Github. This can follow any standard practice with
 recognisable pre- and postfixes, e.g.
 `v1.0.3`, `1.0.3`, `1.1`, `1.3rc`, `1.3.2pl2`.
 
+By default, updating will take into account all available major versions unless
+you set `blockMajorVersionUpdates()`. It's useful to block updates between major
+versions where, for example, support for two major versions overlaps subject to
+a user option or some other transition point.
+
 If you wish to update to a non-stable version, for example where users want to
 update according to a development track, you can set the stability flag for the
 Github strategy. By default this is set to `stable` or, in constant form,
@@ -188,6 +194,14 @@ If you want to ignore stability and just update to the most recent version regar
 $updater->getStrategy()->setStability('any');
 ```
 
+You can prevent updates to the next significant major version (e.g. 1.x to 2.x),
+for example, if you want the user to specifically agree to it or you have specific
+pre-conditions before doing so, using:
+
+```php
+$updater->getStrategy()->blockMajorVersionUpdates();
+```
+
 ### Rollback Support
 
 The Updater automatically copies a backup of the original phar to myname-old.phar.

src/Strategy/GithubStrategy.php

@@ -58,6 +58,11 @@ class GithubStrategy implements StrategyInterface
      */
     private $stability = self::STABLE;
 
+    /**
+     * @var bool
+     */
+    private $allowMajor = true;
+
     /**
      * Download the remote Phar file.
      *
@@ -101,6 +106,11 @@ public function getCurrentRemoteVersion(Updater $updater)
         }
 
         $versions = array_keys($package['package']['versions']);
+
+        if (false === $this->allowMajor) {
+            $versions = $this->filterByLocalMajorVersion($versions);
+        }
+
         $versionParser = new VersionParser($versions);
         if ($this->getStability() === self::STABLE) {
             $this->remoteVersion = $versionParser->getMostRecentStable();
@@ -181,6 +191,11 @@ public function getPharName()
         return $this->pharName;
     }
 
+    public function blockMajorVersionUpdates()
+    {
+        $this->allowMajor = false;
+    }
+
     /**
      * Set target stability
      *
@@ -226,4 +241,20 @@ protected function getDownloadUrl(array $package)
         );
         return $downloadUrl;
     }
+
+    /**
+     * Filter a list of versions to those that match the current local version.
+     *
+     * @param string[] $versions
+     * @return string[]
+     */
+    private function filterByLocalMajorVersion(array $versions)
+    {
+        list($localMajorVersion, ) = explode('.', $this->localVersion, 2);
+
+        return array_filter($versions, function ($version) use ($localMajorVersion) {
+            list($majorVersion, ) = explode('.', $version, 2);
+            return $majorVersion === $localMajorVersion;
+        });
+    }
 }