Allow specifying stability when wanting a compatible PECL version

.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

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:
 

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