Allow a dependency to name the Grav generation it is for

A plugin supporting both 1.7 and 2.0 frequently needs a different version of
the same dependency on each, and had no way to say so. A `dependencies` entry
now takes an optional `grav` key using the same vocabulary as
`compatibility.grav`; entries without one apply everywhere, so every existing
blueprint behaves exactly as before.

A qualified entry beats an unqualified one for the same package rather than
merging with it, because the merge keeps the higher of two versions and would
discard a deliberately lower requirement for this generation.

Older core reads only `name` and `version`, so it would apply every entry
unconditionally and merge to the highest version. The documented rule is to
declare a `grav` dependency naming a core new enough to understand this and
list it first, so such an install stops with "please update Grav" instead. An
audit of the 180 blueprints in the workspace found 164 of 167 already list
grav first, and the only two genuinely at risk are legacy themes that would
not use this.

Author: rhukster

CHANGELOG.md

@@ -1,6 +1,9 @@
 # v2.0.24
 ## 09/03/2026
 
+1. [](#new)
+    * **A dependency can now name the generation of Grav it is for.** A plugin that supports both 1.7 and 2.0 often needs a different version of the same dependency on each, so a `dependencies` entry takes an optional `grav` key: `- { name: form, version: '>=9.1.0', grav: '2.0' }`. Entries without it apply everywhere, so existing blueprints are unchanged. See [Plugin Compatibility](https://learn.getgrav.org/20/plugins/plugin-compatibility#requiring-different-versions-per-grav-generation)
+
 1. [](#bugfix)
     * Installing a package whose dependency is not in the GPM index now says so and carries on, instead of stopping the command with a PHP fatal error. A plugin that still asks for the Grav 1.7 admin plugin was enough to trigger it [getgrav/grav-premium-issues#618](https://github.com/getgrav/grav-premium-issues/issues/618)
     * A plugin that asks for the `admin` plugin now has that read as Admin 2 on Grav 2, so a plugin written for both 1.7 and 2.0 installs instead of failing on a dependency that cannot exist there. The version it asks for is not carried over, because it describes the old admin's numbering [getgrav/grav-premium-issues#618](https://github.com/getgrav/grav-premium-issues/issues/618)

system/src/Grav/Common/GPM/GPM.php

@@ -1339,6 +1339,79 @@ private function firstVersionIsLower($firstVersion, $secondVersion)
      * @param array $dependencies The dependencies array
      * @return array
      */
+    /**
+     * Keep only the dependency entries that apply to the Grav running now.
+     *
+     * An entry may carry an optional `grav` key naming the generation(s) it is
+     * for, spelled the way `compatibility.grav` spells them:
+     *
+     *     dependencies:
+     *       - { name: grav, version: '>=2.0.25' }
+     *       - { name: form, version: '>=7.0.0', grav: '1.7' }
+     *       - { name: form, version: '>=9.1.0', grav: '2.0' }
+     *
+     * An entry with no `grav` key applies everywhere, so every blueprint
+     * written before this existed behaves exactly as it did.
+     *
+     * Where a package has both a qualified entry for this generation and an
+     * unqualified one, the qualified entry wins outright rather than being
+     * merged with it. Merging takes the higher of two versions, which would
+     * silently ignore a deliberately lower requirement for this generation.
+     *
+     * Note for anyone adding a qualified entry: a Grav older than the one that
+     * introduced this reads `name` and `version` and ignores `grav` entirely,
+     * so it would apply every entry unconditionally and merge them to the
+     * highest version. Declare a `grav` dependency naming a core new enough to
+     * understand this, and list it before any qualified entry, so such an
+     * install stops with "please update Grav" instead.
+     *
+     * @param  array $dependencies Raw blueprint `dependencies` entries.
+     * @return array
+     */
+    protected function filterDependenciesForGeneration($dependencies): array
+    {
+        $generation = self::gravGeneration();
+
+        $applies = [];
+        $qualified = [];
+        foreach ((array)$dependencies as $dependency) {
+            if (!is_array($dependency)) {
+                $applies[] = $dependency;
+                continue;
+            }
+
+            $for = $dependency['grav'] ?? null;
+            if ($for === null || $for === '' || $for === []) {
+                $applies[] = $dependency;
+                continue;
+            }
+
+            foreach ((array)$for as $named) {
+                if ((int)$named === (int)$generation) {
+                    $applies[] = $dependency;
+                    if (isset($dependency['name'])) {
+                        $qualified[$dependency['name']] = true;
+                    }
+                    break;
+                }
+            }
+        }
+
+        if (!$qualified) {
+            return $applies;
+        }
+
+        // Drop the unqualified entries for any package that also named this
+        // generation explicitly.
+        return array_values(array_filter($applies, static function ($dependency) use ($qualified) {
+            if (!is_array($dependency) || !isset($dependency['name'])) {
+                return true;
+            }
+
+            return !isset($qualified[$dependency['name']]) || isset($dependency['grav']);
+        }));
+    }
+
     private function calculateMergedDependenciesOfPackage($packageName, $dependencies)
     {
         $packageData = $this->findPackage($packageName);
@@ -1350,7 +1423,7 @@ private function calculateMergedDependenciesOfPackage($packageName, $dependencie
             return $dependencies;
         }
 
-        foreach ($packageData->dependencies as $dependency) {
+        foreach ($this->filterDependenciesForGeneration($packageData->dependencies) as $dependency) {
             $dependencyName = $dependency['name'] ?? null;
             if (!$dependencyName) {
                 continue;

tests/unit/Grav/Common/GPM/GPMTest.php

@@ -351,6 +351,67 @@ public function testDeclaresGravCompatibility(): void
         self::assertSame($isGrav2 ? '2.0' : '1.7', GPM::gravGeneration());
     }
 
+    /**
+     * A dependency entry may name the Grav generation(s) it applies to. Entries
+     * for another generation are skipped; entries with no `grav` key apply
+     * everywhere, so existing blueprints are unaffected.
+     */
+    public function testDependenciesCanBeQualifiedByGravGeneration(): void
+    {
+        $isGrav2 = ((int)GRAV_VERSION) >= 2;
+        $mine  = $isGrav2 ? '2.0' : '1.7';
+        $other = $isGrav2 ? '1.7' : '2.0';
+
+        $this->gpm->data = [
+            'dual' => (object)[
+                'dependencies' => [
+                    ['name' => 'always', 'version' => '>=1.0.0'],
+                    ['name' => 'only-mine', 'version' => '>=2.0.0', 'grav' => $mine],
+                    ['name' => 'only-other', 'version' => '>=3.0.0', 'grav' => $other],
+                    ['name' => 'listed-both', 'version' => '>=4.0.0', 'grav' => ['1.7', '2.0']],
+                ]
+            ],
+        ];
+
+        $merged = $this->invokeMerge('dual');
+
+        self::assertSame('>=1.0.0', $merged['always'] ?? null, 'an unqualified entry always applies');
+        self::assertSame('>=2.0.0', $merged['only-mine'] ?? null, 'an entry for this generation applies');
+        self::assertArrayNotHasKey('only-other', $merged, 'an entry for another generation is skipped');
+        self::assertSame('>=4.0.0', $merged['listed-both'] ?? null, 'a list naming this generation applies');
+    }
+
+    /**
+     * A qualified entry beats an unqualified one for the same package instead
+     * of being merged with it — merging keeps the higher version, which would
+     * throw away a deliberately lower requirement for this generation.
+     */
+    public function testQualifiedDependencyBeatsUnqualifiedOne(): void
+    {
+        $isGrav2 = ((int)GRAV_VERSION) >= 2;
+        $mine = $isGrav2 ? '2.0' : '1.7';
+
+        $this->gpm->data = [
+            'pkg' => (object)[
+                'dependencies' => [
+                    ['name' => 'form', 'version' => '>=9.0.0'],
+                    ['name' => 'form', 'version' => '>=7.0.0', 'grav' => $mine],
+                ]
+            ],
+        ];
+
+        self::assertSame('>=7.0.0', $this->invokeMerge('pkg')['form'] ?? null);
+    }
+
+    /** Run the private merge for one package and return the resulting map. */
+    private function invokeMerge(string $package): array
+    {
+        $method = new ReflectionMethod(GPM::class, 'calculateMergedDependenciesOfPackage');
+        $method->setAccessible(true);
+
+        return $method->invoke($this->gpm, $package, []);
+    }
+
     /**
      * A plugin supporting both generations that asks for `admin` means "the
      * admin panel". On Grav 2 that is admin2, so the requirement is met there