From 02c0e027bf13de32cc416880664a8c475ee7e632 Mon Sep 17 00:00:00 2001
From: Michele Locati <michele@locati.it>
Date: Thu, 9 Nov 2023 15:01:33 +0100
Subject: [PATCH] Allow specifying stability when wanting a compatible PECL
 version (#833)

---
 .github/workflows/test-extensions.yml |  1 +
 README.md                             |  9 +++++++++
 install-php-extensions                | 29 +++++++++++++++++++++++----
 scripts/test-installversion           |  5 +++--
 4 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/test-extensions.yml b/.github/workflows/test-extensions.yml
index cb9cdd0..1d31b41 100644
--- a/.github/workflows/test-extensions.yml
+++ b/.github/workflows/test-extensions.yml
@@ -114,6 +114,7 @@ jobs:
           - 3.0.0
           - ^2
           - ^2.8
+          - ^2.8@stable
     steps:
       - name: Checkout
         uses: actions/checkout@v2
diff --git a/README.md b/README.md
index f2544a2..87e7bd1 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,15 @@ install-php-extensions xdebug-^2
 install-php-extensions xdebug-^2.8
 ```
 
+Please remark that with the syntax above you'll get the vary latest compatible version, which may be unstable. In order to install the most recent *stable* version, you can append `@stable`:
+
+```sh
+# Install the most recent STABLE xdebug 3.x version (for example 3.2.2)
+install-php-extensions xdebug-^3@stable
+```
+
+(valid suffixes are: `@snapshot`, `@devel`, `@alpha`, `@beta`, and `@stable`)
+
 Pre-release versions extensions available on `PECL` can be setup by suffixing the extension's name with its state i.e. `alpha`, `beta`, `rc`, `preview`, `devel` or `snapshot`.
 For example:
 
diff --git a/install-php-extensions b/install-php-extensions
index 27e461d..86d8db0 100755
--- a/install-php-extensions
+++ b/install-php-extensions
@@ -371,19 +371,40 @@ resolveWantedPHPModuleVersion() {
 		printf '%s' "$resolveWantedPHPModuleVersion_raw"
 		return
 	fi
+	case "$resolveWantedPHPModuleVersion_afterCaret" in
+		?*@snapshot | ?*@devel | ?*@alpha | ?*@beta | ?*@stable)
+			resolveWantedPHPModuleVersion_wantedStability="${resolveWantedPHPModuleVersion_afterCaret##*@}"
+			resolveWantedPHPModuleVersion_wantedVersion="${resolveWantedPHPModuleVersion_afterCaret%@*}"
+			;;
+		*)
+			resolveWantedPHPModuleVersion_wantedStability=''
+			resolveWantedPHPModuleVersion_wantedVersion="$resolveWantedPHPModuleVersion_afterCaret"
+			;;
+	esac
 	resolveWantedPHPModuleVersion_xml="$(curl -sSLf "http://pecl.php.net/rest/r/$1/allreleases.xml")"
-	resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_xml" | tr -s ' \t\r\n' ' ' | sed -r 's# *<#\n<#g' | grep '<v>' | sed 's#<v>##g' | sed 's# ##g')"
+	# remove line endings, collapse spaces
+	resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_xml" | tr -s ' \t\r\n' ' ')"
+	# one line per release (eg <r><v>1.2.3</v><s>stable</s></r>)
+	resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_versions" | sed -r 's#<r#\n<r#g')"
+	if test -n "$resolveWantedPHPModuleVersion_wantedStability"; then
+		# keep the lines with the wanted stability
+		resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_versions" | grep "<s>$resolveWantedPHPModuleVersion_wantedStability</s>")"
+	fi
+	# remove everything's up to '<v>' (included)
+	resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_versions" | sed 's#^.*<v>##')"
+	# keep just the versions
+	resolveWantedPHPModuleVersion_versions="$(printf '%s' "$resolveWantedPHPModuleVersion_versions" | cut -d'<' -f1)"
 	resetIFS
 	for resolveWantedPHPModuleVersion_version in $resolveWantedPHPModuleVersion_versions; do
-		resolveWantedPHPModuleVersion_suffix="${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_afterCaret}"
-		if test "$resolveWantedPHPModuleVersion_version" != "${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_afterCaret.}"; then
+		resolveWantedPHPModuleVersion_suffix="${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_wantedVersion}"
+		if test "$resolveWantedPHPModuleVersion_version" != "${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_wantedVersion.}"; then
 			# Example: looking for 1.0, found 1.0.1
 			printf '%s' "$resolveWantedPHPModuleVersion_version"
 			return
 		fi
 	done
 	for resolveWantedPHPModuleVersion_version in $resolveWantedPHPModuleVersion_versions; do
-		resolveWantedPHPModuleVersion_suffix="${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_afterCaret}"
+		resolveWantedPHPModuleVersion_suffix="${resolveWantedPHPModuleVersion_version#$resolveWantedPHPModuleVersion_wantedVersion}"
 		if test "$resolveWantedPHPModuleVersion_version" = "$resolveWantedPHPModuleVersion_suffix"; then
 			continue
 		fi
diff --git a/scripts/test-installversion b/scripts/test-installversion
index 3114d99..4433daa 100755
--- a/scripts/test-installversion
+++ b/scripts/test-installversion
@@ -5,7 +5,8 @@ set -o errexit
 set -o nounset
 
 WANTED_VERSION="${1:-}"
-WANTED_VERSION_AFTERCARET="${1#^}"
+WANTED_VERSION_BASE="${1#^}"
+WANTED_VERSION_BASE="${WANTED_VERSION_BASE%@*}"
 INSTALLME=xdebug
 if test -n "$WANTED_VERSION"; then
 	INSTALLME="$INSTALLME-$1"
@@ -18,7 +19,7 @@ if test -z "$WANTED_VERSION"; then
 	printf 'Installing the default version worked (we installed version %s)\n' "$INSTALLED_VERSION"
 elif test "$WANTED_VERSION" = "$INSTALLED_VERSION"; then
 	printf 'Installing specific version %s worked\n' "$WANTED_VERSION"
-elif test "$WANTED_VERSION" != "$WANTED_VERSION_AFTERCARET" && test "${INSTALLED_VERSION#$WANTED_VERSION_AFTERCARET.}" != "$INSTALLED_VERSION"; then
+elif test "$WANTED_VERSION" != "$WANTED_VERSION_BASE" && test "${INSTALLED_VERSION#$WANTED_VERSION_BASE.}" != "$INSTALLED_VERSION"; then
 	printf 'Installing version compatible with %s worked (we installed version %s)\n' "$WANTED_VERSION" "$INSTALLED_VERSION"
 else
 	printf 'We wanted to install version %s, but we installed %s\n' "$WANTED_VERSION" "$INSTALLED_VERSION" >&2