fix: report release tag or commit as extension version

.github/workflows/job-arrow-extension.yml

@@ -20,6 +20,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -127,6 +129,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -179,17 +183,26 @@ jobs:
           pie --version
 
       - name: Prepare local package for PIE installation
-        working-directory: src/extension/arrow-ext
         run: |
+          # git archive applies export-subst like GitHub release archives, so the build resolves its version from .git_archival.txt
+          git archive HEAD src/extension/arrow-ext | tar -x -C "$RUNNER_TEMP"
+          cd "$RUNNER_TEMP/src/extension/arrow-ext"
           jq '. + {"version": "0.0.9999"}' composer.json > composer.tmp.json
           mv composer.tmp.json composer.json
 
       - name: Install extension via PIE (from local)
         run: |
           sudo pie repository:remove packagist.org
-          sudo pie repository:add path ${{ github.workspace }}/src/extension/arrow-ext
+          sudo pie repository:add path "$RUNNER_TEMP/src/extension/arrow-ext"
           sudo env "PATH=$PATH" "LIBCLANG_PATH=$LIBCLANG_PATH" ${CLANG_PATH:+"CLANG_PATH=$CLANG_PATH"} "RUSTUP_TOOLCHAIN=$RUSTUP_TOOLCHAIN" "CARGO_HOME=$CARGO_HOME" "RUSTUP_HOME=$RUSTUP_HOME" pie install flow-php/arrow-ext:0.0.9999@dev
 
       - name: Verify extension is loaded
         run: |
           php -m | grep arrow
+
+      - name: Verify extension version
+        run: |
+          expected="$(git describe --tags --match '[0-9]*' | sed -E 's/-([0-9]+)-(g[0-9a-f]+)$/+\1.\2/')"
+          actual="$(php -r 'echo phpversion("arrow");')"
+          echo "expected: $expected, actual: $actual"
+          test "$actual" = "$expected"

.github/workflows/job-flow-php-extension.yml

@@ -20,6 +20,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -124,6 +126,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -176,15 +180,17 @@ jobs:
           pie --version
 
       - name: Prepare local package for PIE installation
-        working-directory: src/extension/flow-php-ext
         run: |
+          # git archive applies export-subst like GitHub release archives, so the build resolves its version from .git_archival.txt
+          git archive HEAD src/extension/flow-php-ext | tar -x -C "$RUNNER_TEMP"
+          cd "$RUNNER_TEMP/src/extension/flow-php-ext"
           jq '. + {"version": "0.0.9999"}' composer.json > composer.tmp.json
           mv composer.tmp.json composer.json
 
       - name: Install extension via PIE (from local)
         run: |
           sudo pie repository:remove packagist.org
-          sudo pie repository:add path ${{ github.workspace }}/src/extension/flow-php-ext
+          sudo pie repository:add path "$RUNNER_TEMP/src/extension/flow-php-ext"
           sudo env "PATH=$PATH" "LIBCLANG_PATH=$LIBCLANG_PATH" ${CLANG_PATH:+"CLANG_PATH=$CLANG_PATH"} "RUSTUP_TOOLCHAIN=$RUSTUP_TOOLCHAIN" "CARGO_HOME=$CARGO_HOME" "RUSTUP_HOME=$RUSTUP_HOME" pie install flow-php/flow-php-ext:0.0.9999@dev
 
       - name: Enable extension
@@ -194,3 +200,10 @@ jobs:
       - name: Verify extension is loaded
         run: |
           php -m | grep flow_php
+
+      - name: Verify extension version
+        run: |
+          expected="$(git describe --tags --match '[0-9]*' | sed -E 's/-([0-9]+)-(g[0-9a-f]+)$/+\1.\2/')"
+          actual="$(php -r 'echo phpversion("flow_php");')"
+          echo "expected: $expected, actual: $actual"
+          test "$actual" = "$expected"

.github/workflows/job-pg-query-extension.yml

@@ -17,6 +17,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -68,6 +70,8 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          # git describe needs history and tags to resolve the extension version
+          fetch-depth: 0
 
       - name: Setup PHP Environment
         uses: ./.github/actions/setup-php-env
@@ -95,17 +99,26 @@ jobs:
           pie --version
 
       - name: Prepare local package for PIE installation
-        working-directory: src/extension/pg-query-ext
         run: |
+          # git archive applies export-subst like GitHub release archives, so the build resolves its version from .git_archival.txt
+          git archive HEAD src/extension/pg-query-ext | tar -x -C "$RUNNER_TEMP"
+          cd "$RUNNER_TEMP/src/extension/pg-query-ext"
           jq '. + {"version": "0.0.9999"}' composer.json > composer.tmp.json
           mv composer.tmp.json composer.json
 
       - name: Install extension via PIE (from local)
         run: |
           sudo pie repository:remove packagist.org
-          sudo pie repository:add path ${{ github.workspace }}/src/extension/pg-query-ext
+          sudo pie repository:add path "$RUNNER_TEMP/src/extension/pg-query-ext"
           sudo pie install flow-php/pg-query-ext:0.0.9999@dev
 
       - name: Verify extension is loaded
         run: |
           php -m | grep pg_query
+
+      - name: Verify extension version
+        run: |
+          expected="$(git describe --tags --match '[0-9]*' | sed -E 's/-([0-9]+)-(g[0-9a-f]+)$/+\1.\2/')"
+          actual="$(php -r 'echo phpversion("pg_query");')"
+          echo "expected: $expected, actual: $actual"
+          test "$actual" = "$expected"

.nix/pkgs/php-pg-query-ext/package.nix

@@ -66,6 +66,8 @@ php.buildPecl {
 
   buildInputs = [ protobufc libpg_query ];
 
+  env.PG_QUERY_EXT_VERSION = "dev";
+
   configureFlags = [
     "--with-pg-query=${libpg_query}"
   ];

documentation/upgrading.md

@@ -1428,9 +1428,9 @@ Registering the commands in your own console application: drop the `setName()` /
 
 ### 98) `flow-php/flow-php-ext` - the `flow_php` extension must be reinstalled
 
-| Before                     | After                                  |
-|----------------------------|----------------------------------------|
-| `flow_php` extension 0.1.0 | 0.3.0, required by this `flow-php/etl` |
+| Before                     | After                                       |
+|----------------------------|---------------------------------------------|
+| `flow_php` extension 0.1.0 | same version as this `flow-php/etl` release |
 
 Reinstall it with the new release: `pie install flow-php/flow-php-ext`.
 

src/extension/arrow-ext/.git_archival.txt

@@ -0,0 +1 @@
+describe-name: $Format:%(describe:tags=true,match=[0-9]*)$

src/extension/arrow-ext/.gitattributes

@@ -6,6 +6,9 @@
 /.gitattributes export-ignore
 /.gitignore export-ignore
 
+# Expand the version placeholder in release archives
+/.git_archival.txt export-subst
+
 # Ensure consistent line endings
 *.php text eol=lf
 *.rs text eol=lf

src/extension/arrow-ext/Cargo.toml

@@ -1,6 +1,5 @@
 [package]
 name = "arrow"
-version = "0.1.0"
 edition = "2021"
 publish = false
 

src/extension/arrow-ext/build.rs

@@ -1,20 +1,11 @@
+use std::path::Path;
+use std::process::Command;
+
 fn main() {
-    let version = std::env::var("ARROW_VERSION")
-        .ok()
-        .filter(|s| !s.is_empty())
-        .or_else(|| {
-            std::process::Command::new("git")
-                .args(["describe", "--tags", "--always"])
-                .output()
-                .ok()
-                .filter(|o| o.status.success())
-                .and_then(|o| String::from_utf8(o.stdout).ok())
-                .map(|s| s.trim().to_string())
-                .filter(|s| !s.is_empty())
-        })
-        .unwrap_or_else(|| env!("CARGO_PKG_VERSION").to_string());
+    let version = extension_version("ARROW_VERSION");
 
     println!("cargo:rustc-env=ARROW_VERSION={version}");
+    println!("cargo:rerun-if-changed=Cargo.lock");
 
     let arrow_version =
         resolve_dep_version("arrow-schema").unwrap_or_else(|| "unknown".to_string());
@@ -24,6 +15,74 @@ fn main() {
     println!("cargo:rustc-env=PARQUET_LIB_VERSION={parquet_version}");
 }
 
+fn extension_version(env_name: &str) -> String {
+    println!("cargo:rerun-if-env-changed={env_name}");
+    println!("cargo:rerun-if-changed=.git_archival.txt");
+
+    let describe = std::env::var(env_name)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .or_else(archived_describe)
+        .or_else(git_describe)
+        .unwrap_or_else(|| {
+            panic!("cannot determine the extension version: set {env_name}, build from a GitHub release archive, or build from a git checkout with tags")
+        });
+
+    as_semver(&describe)
+}
+
+/// GitHub archives expand the `$Format:...$` placeholder (export-subst), a git checkout leaves it verbatim.
+fn archived_describe() -> Option<String> {
+    std::fs::read_to_string(".git_archival.txt")
+        .ok()?
+        .lines()
+        .find_map(|line| line.strip_prefix("describe-name: "))
+        .map(str::trim)
+        .filter(|describe| !describe.is_empty() && !describe.starts_with("$Format"))
+        .map(str::to_string)
+}
+
+fn git_describe() -> Option<String> {
+    let describe = git(&["describe", "--tags", "--match", "[0-9]*"])?;
+
+    for path in ["HEAD", "refs/heads", "refs/tags", "packed-refs"] {
+        if let Some(watched) = git(&["rev-parse", "--path-format=absolute", "--git-path", path]) {
+            if Path::new(&watched).exists() {
+                println!("cargo:rerun-if-changed={watched}");
+            }
+        }
+    }
+
+    Some(describe)
+}
+
+fn git(args: &[&str]) -> Option<String> {
+    Command::new("git")
+        .args(args)
+        .output()
+        .ok()
+        .filter(|output| output.status.success())
+        .and_then(|output| String::from_utf8(output.stdout).ok())
+        .map(|stdout| stdout.trim().to_string())
+        .filter(|stdout| !stdout.is_empty())
+}
+
+/// `0.43.0-107-gf998a45d0` (git describe) becomes `0.43.0+107.gf998a45d0`, semver build metadata Composer reads as 0.43.0.
+fn as_semver(describe: &str) -> String {
+    let mut parts = describe.rsplitn(3, '-');
+
+    match (parts.next(), parts.next(), parts.next()) {
+        (Some(hash), Some(distance), Some(tag))
+            if hash.starts_with('g')
+                && !distance.is_empty()
+                && distance.bytes().all(|b| b.is_ascii_digit()) =>
+        {
+            format!("{tag}+{distance}.{hash}")
+        }
+        _ => describe.to_string(),
+    }
+}
+
 fn resolve_dep_version(crate_name: &str) -> Option<String> {
     let lock_contents = std::fs::read_to_string("Cargo.lock").ok()?;
     let needle = format!("name = \"{crate_name}\"");

src/extension/arrow-ext/src/lib.rs

@@ -45,6 +45,7 @@ pub unsafe extern "C" fn module_startup(_type: i32, _module_number: i32) -> i32
 #[php(startup = "module_startup")]
 pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
     module
+        .version(env!("ARROW_VERSION"))
         .info_function(php_module_info)
         .class::<Reader>()
         .class::<Writer>()

src/extension/arrow-ext/tests/phpt/038_extension_version.phpt

@@ -0,0 +1,8 @@
+--TEST--
+extension version is the release tag, or the last tag with commit distance and hash
+--FILE--
+<?php
+var_dump(preg_match('/^\d+\.\d+\.\d+(\+\d+\.g[0-9a-f]+)?$/', phpversion('arrow')));
+?>
+--EXPECT--
+int(1)

src/extension/flow-php-ext/.git_archival.txt

@@ -0,0 +1 @@
+describe-name: $Format:%(describe:tags=true,match=[0-9]*)$

src/extension/flow-php-ext/.gitattributes

@@ -6,6 +6,9 @@
 /.gitattributes export-ignore
 /.gitignore export-ignore
 
+# Expand the version placeholder in release archives
+/.git_archival.txt export-subst
+
 # Ensure consistent line endings
 *.php text eol=lf
 *.rs text eol=lf

src/extension/flow-php-ext/Cargo.toml

@@ -1,6 +1,5 @@
 [package]
 name = "flow_php"
-version = "0.3.0"
 edition = "2021"
 publish = false