ext/gmp: expose the possibility of being a prime in gmp_prevprime (#22907)

Follow up #22807 to expose the "definitelyPrime" parameter in the
gmp_prevprime function to indicate the possibility of whether the outputted
number is actually a prime.

Author: LamentXU123

NEWS

@@ -3,6 +3,8 @@ PHP                                                                        NEWS
 ?? ??? ????, PHP 8.6.0beta1
 
 - GMP:
+  . Added optional $definitely_prime output parameter to gmp_prevprime().
+    (Weilin Du)
   . Added gmp_powm_sec(). (Weilin Du)
 
 30 Jul 2026, PHP 8.6.0alpha3

UPGRADING

@@ -275,9 +275,11 @@ PHP 8.6 UPGRADE NOTES
   . Added gmp_powm_sec() for side-channel quiet modular exponentiation.
     Requires GNU MP 5.0.0 or later.
   . Added gmp_prevprime() to get the largest prime smaller than the given
-    number. A ValueError is thrown if no such prime exists. This function is
-    available only when PHP is built against GNU MP 6.3.0 or later; it is not
-    available on official Windows builds using MPIR.
+    number. The optional $definitely_prime output parameter indicates whether
+    the returned number is definitely prime, as opposed to probably prime.
+    A ValueError is thrown if no such prime exists. This function is available
+    only when PHP is built against GNU MP 6.3.0 or later; it is not available
+    on official Windows builds using MPIR.
 
 - Intl:
   . Added Locale::getDisplayKeyword() and Locale::getDisplayKeywordValue(),

ext/gmp/gmp.c

@@ -1087,10 +1087,13 @@ GMP_UNARY_OP_FUNCTION(nextprime);
 ZEND_FUNCTION(gmp_prevprime)
 {
 	mpz_ptr gmpnum_a, gmpnum_result;
+	zval *definitely_prime = NULL;
 	int res;
 
-	ZEND_PARSE_PARAMETERS_START(1, 1)
+	ZEND_PARSE_PARAMETERS_START(1, 2)
 		GMP_Z_PARAM_INTO_MPZ_PTR(gmpnum_a)
+		Z_PARAM_OPTIONAL
+		Z_PARAM_ZVAL(definitely_prime)
 	ZEND_PARSE_PARAMETERS_END();
 
 	if (mpz_cmp_ui(gmpnum_a, 2) <= 0) {
@@ -1106,6 +1109,9 @@ ZEND_FUNCTION(gmp_prevprime)
 	INIT_GMP_RETVAL(gmpnum_result);
 	res = mpz_prevprime(gmpnum_result, gmpnum_a);
 	ZEND_ASSERT(res);
+	if (definitely_prime) {
+		ZEND_TRY_ASSIGN_REF_BOOL(definitely_prime, res == 2);
+	}
 }
 /* }}} */
 #endif

ext/gmp/gmp.stub.php

@@ -188,7 +188,8 @@ function gmp_hamdist(GMP|int|string $num1, GMP|int|string $num2): int {}
 function gmp_nextprime(GMP|int|string $num): GMP {}
 
 #ifdef HAVE___GMPZ_PREVPRIME
-function gmp_prevprime(GMP|int|string $num): GMP {}
+/** @param bool $definitely_prime */
+function gmp_prevprime(GMP|int|string $num, &$definitely_prime = null): GMP {}
 #endif
 
 function gmp_binomial(GMP|int|string $n, int $k): GMP {}

ext/gmp/gmp_arginfo.h

@@ -19,16 +19,42 @@ foreach ([-1, 0, 1, 2] as $value) {
     }
 }
 
+$definitelyPrime = null;
+try {
+    var_dump(gmp_prevprime(2, $definitelyPrime));
+} catch (\ValueError $e) {
+    echo $e->getMessage() . \PHP_EOL;
+}
+var_dump($definitelyPrime);
+
 var_dump(gmp_strval(gmp_prevprime(3)));
 var_dump(gmp_strval(gmp_prevprime(4)));
 var_dump(gmp_strval(gmp_prevprime(10000)));
 
+$definitelyPrime = null;
+var_dump(gmp_strval(gmp_prevprime(3, $definitelyPrime)));
+var_dump($definitelyPrime);
+
+$probablePrime = gmp_nextprime(gmp_pow(10, 80));
+$definitelyPrime = null;
+$previousPrime = gmp_prevprime(gmp_add($probablePrime, 1), $definitelyPrime);
+var_dump(gmp_cmp($previousPrime, $probablePrime) === 0);
+var_dump(is_bool($definitelyPrime));
+var_dump($definitelyPrime === (gmp_prob_prime($previousPrime) === 2));
+
 ?>
 --EXPECT--
 gmp_prevprime(): Argument #1 ($num) must be greater than 2
 gmp_prevprime(): Argument #1 ($num) must be greater than 2
 gmp_prevprime(): Argument #1 ($num) must be greater than 2
 gmp_prevprime(): Argument #1 ($num) must be greater than 2
+gmp_prevprime(): Argument #1 ($num) must be greater than 2
+NULL
 string(1) "2"
 string(1) "3"
 string(4) "9973"
+string(1) "2"
+bool(true)
+bool(true)
+bool(true)
+bool(true)