change: Deprecate Gherkin::VERSION and change how file caches are namespaced

The `Gherkin::VERSION` constant has not been updated for recent releases,
and will not be part of our release process in the future.

This constant was only being used internally to ensure that any pre-existing
file caches are invalidated when a different version of the parser is
installed. I have switched this to get a version from the composer runtime
API, which should be at least as reliable as the previous hardcoded
constant for this purpose.

Author: acoulton

composer.json

@@ -14,7 +14,8 @@
     ],
 
     "require": {
-        "php": "8.1.* || 8.2.* || 8.3.* || 8.4.*"
+        "php": "8.1.* || 8.2.* || 8.3.* || 8.4.*",
+        "composer-runtime-api": "^2.2"
     },
 
     "require-dev": {

src/Behat/Gherkin/Cache/FileCache.php

@@ -11,8 +11,8 @@
 namespace Behat\Gherkin\Cache;
 
 use Behat\Gherkin\Exception\CacheException;
-use Behat\Gherkin\Gherkin;
 use Behat\Gherkin\Node\FeatureNode;
+use Composer\InstalledVersions;
 
 /**
  * File cache.
@@ -24,6 +24,17 @@ class FileCache implements CacheInterface
 {
     private $path;
 
+    /**
+     * Used as part of the cache directory path to invalidate cache if the installed package version changes.
+     */
+    private static function getGherkinVersionHash(): string
+    {
+        $version = InstalledVersions::getVersion('behat/gherkin');
+
+        // Composer version strings can contain arbitrary content so hash for filesystem safety
+        return md5($version);
+    }
+
     /**
      * Initializes file cache.
      *
@@ -33,7 +44,7 @@ class FileCache implements CacheInterface
      */
     public function __construct($path)
     {
-        $this->path = rtrim($path, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . 'v' . Gherkin::VERSION;
+        $this->path = rtrim($path, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . self::getGherkinVersionHash();
 
         if (!is_dir($this->path)) {
             @mkdir($this->path, 0777, true);

src/Behat/Gherkin/Gherkin.php

@@ -23,6 +23,11 @@
  */
 class Gherkin
 {
+    /**
+     * @deprecated this constant will not be updated for releases after 4.8.0 and will be removed in the next major.
+     * You can use composer's runtime API to get the behat version if you need it. Note that composer's versions will
+     * not always be simple numeric values.
+     */
     public const VERSION = '4.8.0';
 
     /**