Support pre-release vesions of FHIR (#193)

Author: dcarbone

src/Version/SourceMetadata.php

@@ -31,6 +31,18 @@ class SourceMetadata
     private string $_fhirGenerationDate;
     private string $_fhirVersion;
 
+    /**
+     * The base version string with any pre-release suffix stripped.
+     * e.g. 'v6.0.0-ballot4' -> 'v6.0.0'.
+     * Used for all Semver range comparisons.
+     */
+    private string $_fhirVersionBase;
+
+    /**
+     * The pre-release identifier, if any (e.g. 'ballot4').  Null for GA releases.
+     */
+    private null|string $_fhirPreRelease = null;
+
     public function __construct(string $schemPath)
     {
         $this->_schemaPath = $schemPath;
@@ -65,14 +77,14 @@ public function getSemanticVersion(bool $trimmed): string
     }
 
     /**
-     * Return the shortenend representation of the FHIR semantic version containing only Manjor.Minor values.
+     * Return the shortenend representation of the FHIR semantic version containing only Major.Minor values.
      *
      * @return string
      */
     public function getShortVersion(): string
     {
         $this->_compile();
-        $v = ltrim($this->_fhirVersion);
+        $v = ltrim($this->_fhirVersionBase, 'v');
         return match (substr_count($v, '.')) {
             1 => $v,
             2 => substr($v, 0, strrpos($v, '.')),
@@ -82,13 +94,43 @@ public function getShortVersion(): string
 
     /**
      * Returns an integer representation of the FHIR semantic version.
+     * Pre-release suffixes are ignored; the integer is derived from the base
+     * version only, so 'v6.0.0-ballot4' and 'v6.0.0' produce the same value.
+     * Use isPreRelease() to distinguish ballot from GA releases.
      *
      * @return int
      */
     public function getVersionInteger(): int
     {
         $this->_compile();
-        return intval(sprintf("%'.-08s", str_replace(['v', '.'], '', $this->_fhirVersion)));
+        return intval(sprintf("%'.-08s", str_replace(['v', '.'], '', $this->_fhirVersionBase)));
+    }
+
+    /**
+     * Returns the pre-release identifier extracted from the FHIR version string,
+     * or null if this is a GA release.
+     *
+     * e.g. 'v6.0.0-ballot4' -> 'ballot4'
+     *      'v5.0.0'         -> null
+     *
+     * @return string|null
+     */
+    public function getPreRelease(): null|string
+    {
+        $this->_compile();
+        return $this->_fhirPreRelease;
+    }
+
+    /**
+     * Returns true when the FHIR source version carries a pre-release suffix
+     * (e.g. '-ballot4').
+     *
+     * @return bool
+     */
+    public function isPreRelease(): bool
+    {
+        $this->_compile();
+        return null !== $this->_fhirPreRelease;
     }
 
     /**
@@ -98,42 +140,59 @@ public function getVersionInteger(): int
      */
     public function isDSTU1(): bool
     {
-        return Semver::satisfies($this->getSemanticVersion(false), '< v1.0.0');
+        return Semver::satisfies($this->_getVersionBase(), '< v1.0.0');
     }
 
     public function isDSTU2(): bool
     {
-        $semver = $this->getSemanticVersion(false);
-        return Semver::satisfies($semver, '>= v1.0.0')
-            && Semver::satisfies($semver, '< v3.0.0');
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v1.0.0')
+            && Semver::satisfies($base, '< v3.0.0');
     }
 
     public function isSTU3(): bool
     {
-        $semver = $this->getSemanticVersion(false);
-        return Semver::satisfies($semver, '>= v3.0.0')
-            && Semver::satisfies($semver, '< v4.0.0');
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v3.0.0')
+            && Semver::satisfies($base, '< v4.0.0');
     }
 
     public function isR4(): bool
     {
-        $semver = $this->getSemanticVersion(false);
-        return Semver::satisfies($semver, '>= v4.0.0')
-            && Semver::satisfies($semver, '< v4.3.0');
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v4.0.0')
+            && Semver::satisfies($base, '< v4.3.0');
     }
 
     public function isR4B(): bool
     {
-        $semver = $this->getSemanticVersion(false);
-        return Semver::satisfies($semver, '>= v4.3.0')
-            && Semver::satisfies($semver, '< v5.0.0');
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v4.3.0')
+            && Semver::satisfies($base, '< v5.0.0');
     }
 
     public function isR5(): bool
     {
-        $semver = $this->getSemanticVersion(false);
-        return Semver::satisfies($semver, '>= v5.0.0')
-            && Semver::satisfies($semver, '< v6.0.0');
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v5.0.0')
+            && Semver::satisfies($base, '< v6.0.0');
+    }
+
+    public function isR6(): bool
+    {
+        $base = $this->_getVersionBase();
+        return Semver::satisfies($base, '>= v6.0.0')
+            && Semver::satisfies($base, '< v7.0.0');
+    }
+
+    /**
+     * Returns the compiled base version (without pre-release suffix) for use
+     * in Semver range comparisons.
+     */
+    private function _getVersionBase(): string
+    {
+        $this->_compile();
+        return $this->_fhirVersionBase;
     }
 
     private function _compile(): void
@@ -180,6 +239,15 @@ private function _compile(): void
                         $version = trim($version);
                         if (str_starts_with($version, 'v')) {
                             $this->_fhirVersion = $version;
+                            // Split off any pre-release suffix (e.g. 'v6.0.0-ballot4').
+                            $dashPos = strpos($version, '-');
+                            if (false !== $dashPos) {
+                                $this->_fhirVersionBase  = substr($version, 0, $dashPos);
+                                $this->_fhirPreRelease   = substr($version, $dashPos + 1);
+                            } else {
+                                $this->_fhirVersionBase = $version;
+                                $this->_fhirPreRelease  = null;
+                            }
                         } else {
                             throw new \LogicException(
                                 sprintf(

template/core/class_fhir_version.php

@@ -38,21 +38,25 @@ class <?php echo $coreFile; ?> implements \JsonSerializable
     public const STU3_MIN_VERSION_INTEGER = 30000000;
     public const R4_MIN_VERSION_INTEGER = 40000000;
     public const R5_MIN_VERSION_INTEGER = 50000000;
+    public const R6_MIN_VERSION_INTEGER = 60000000;
 
     private string $_versionName;
     private string $_fhirSemanticVersion;
     private string $_fhirShortVersion;
     private int $_fhirVersionInteger;
+    private null|string $_fhirPreRelease;
 
     public function __construct(string $versionName,
                                 string $fhirSemanticVersion,
                                 string $fhirShortVersion,
-                                int $fhirVersionInteger)
+                                int $fhirVersionInteger,
+                                null|string $fhirPreRelease = null)
     {
         $this->_versionName = $versionName;
         $this->_fhirSemanticVersion = $fhirSemanticVersion;
         $this->_fhirShortVersion = $fhirShortVersion;
         $this->_fhirVersionInteger = $fhirVersionInteger;
+        $this->_fhirPreRelease = $fhirPreRelease;
     }
 
     public function getName(): string
@@ -75,13 +79,24 @@ public function getFHIRVersionInteger(): int
         return $this->_fhirVersionInteger;
     }
 
+    public function getFHIRPreRelease(): null|string
+    {
+        return $this->_fhirPreRelease;
+    }
+
+    public function isFHIRPreRelease(): bool
+    {
+        return null !== $this->_fhirPreRelease;
+    }
+
     public function jsonSerialize(): \stdClass
     {
         $out = new \stdClass();
         $out->versionName = $this->_versionName;
         $out->fhirSemanticVersion = $this->_fhirSemanticVersion;
         $out->fhirShortversion = $this->_fhirShortVersion;
         $out->fhirVersionInteger = $this->_fhirVersionInteger;
+        $out->fhirPreRelease = $this->_fhirPreRelease;
         return $out;
     }
 

template/core/versions/interface_version.php

@@ -82,6 +82,21 @@ public function getFHIRShortVersion(): string;
      */
     public function getFHIRVersionInteger(): int;
 
+    /**
+     * Must return the pre-release identifier from the FHIR version string (e.g. 'ballot4'),
+     * or null when this is a GA release.
+     *
+     * @return null|string
+     */
+    public function getFHIRPreRelease(): null|string;
+
+    /**
+     * Must return true when the FHIR source version is a pre-release (e.g. a ballot build).
+     *
+     * @return bool
+     */
+    public function isFHIRPreRelease(): bool;
+
     /**
      * Must return the date this FHIR version's source was generated
      *

template/tests/core/mock/class_abstract_mock_type.php

@@ -57,7 +57,8 @@ abstract class <?php echo $coreFile; ?> implements <?php echo $typeInterface; ?>
 
     public function __construct(string $name,
                                 string $versionName = self::DEFAULT_MOCK_VERSION_NAME,
-                                string $semanticVersion = self::DEFAULT_MOCK_SEMANTIC_VERSION)
+                                string $semanticVersion = self::DEFAULT_MOCK_SEMANTIC_VERSION,
+                                null|string $preRelease = null)
     {
         $this->_name = $name;
 
@@ -69,10 +70,11 @@ public function __construct(string $name,
         };
 
         $this->_fhirVersion = new <?php echo $fhirVersion; ?>(
-            $versionName,
-            $semanticVersion,
-            $shortVersion,
-            intval(sprintf("%'.-08s", str_replace(['v', '.'], '', $semanticVersion))),
+            versionName: $versionName,
+            fhirSemanticVersion: $semanticVersion,
+            fhirShortVersion: $shortVersion,
+            fhirVersionInteger: intval(sprintf("%'.-08s", str_replace(['v', '.'], '', $semanticVersion))),
+            fhirPreRelease: $preRelease,
         );
     }
 

template/tests/core/mock/class_mock_version.php

@@ -59,6 +59,7 @@ class <?php echo $coreFile; ?> implements <?php echo $versionInterface; ?>
     public const FHIR_SEMANTIC_VERSION = 'v99.99.99';
     public const FHIR_SHORT_VERSION = 'v9.9';
     public const FHIR_VERSION_INTEGER = 999999999;
+    public const FHIR_PRE_RELEASE = null;
 
     private static <?php echo $fhirVersion; ?> $_fhirVersion;
     private static <?php echo $versionTypeMapInterface; ?> $_typeMap;
@@ -80,10 +81,11 @@ public static function getFHIRVersion(): <?php echo $fhirVersion; ?>
     {
         if (!isset(self::$_fhirVersion)) {
             self::$_fhirVersion = new <?php echo $fhirVersion; ?>(
-                self::NAME,
-                self::FHIR_SEMANTIC_VERSION,
-                self::FHIR_SHORT_VERSION,
-                self::FHIR_VERSION_INTEGER,
+                versionName: self::NAME,
+                fhirSemanticVersion: self::FHIR_SEMANTIC_VERSION,
+                fhirShortVersion: self::FHIR_SHORT_VERSION,
+                fhirVersionInteger: self::FHIR_VERSION_INTEGER,
+                fhirPreRelease: self::FHIR_PRE_RELEASE,
             );
         }
         return self::$_fhirVersion;
@@ -104,6 +106,16 @@ public function getFHIRVersionInteger(): int
         return self::FHIR_VERSION_INTEGER;
     }
 
+    public function getFHIRPreRelease(): null|string
+    {
+        return self::FHIR_PRE_RELEASE;
+    }
+
+    public function isFHIRPreRelease(): bool
+    {
+        return null !== self::FHIR_PRE_RELEASE;
+    }
+
     public function getFHIRGenerationDate(): string
     {
         throw new \BadMethodCallException('Not implemented');