Deprecate and ignore $version parameter of curl_version()

cmb69 · cmb69 · commit 357da6bc5926 · 2019-05-13T08:53:41.000+02:00
`curl_version()`[1] (of ext/curl) makes `curl_version_info()`[2] (of libcurl) available to PHP userland. The latter requires to pass an `age` argument which usually is `CURLVERSION_NOW`, so that the information returned by the runtime matches the declarations used during compile time. For C programs it is simply necessary to pass this information, and in rare occasions it might make sense to pass something else than `CURLVERSION_NOW`. curl.h notes: | The 'CURLVERSION_NOW' is the symbolic name meant to be used by | basically all programs ever that want to get version information. For the PHP binding, using a newer `age` than available at compile time will neither provide the PHP program more information, nor would using an older `age` have tangible benefits. We therefore deprecate the useless `$version` parameter, and if it is passed nonetheless, we use `CURLVERSION_NOW` instead of the supplied value, and raise a warning. [1] <https://www.php.net/manual/en/function.curl-version.php> [2] <https://curl.haxx.se/libcurl/c/curl_version_info.html>
diff --git a/NEWS b/NEWS
@@ -28,6 +28,7 @@ PHP                                                                        NEWS
     (Pierrick)
   . Implemented FR #77711 (CURLFile should support UNICODE filenames). (cmb)
   . Deprecated CURLPIPE_HTTP1. (cmb)
+  . Deprecated $version parameter of curl_version(). (cmb)
 
 - Date:
   . Fixed bug #75232 (print_r of DateTime creating side-effect). (Nikita)
diff --git a/UPGRADING b/UPGRADING
@@ -46,6 +46,9 @@ PHP 7.4 UPGRADE NOTES
     Previously the exception was only thrown on unserialization.
   . Using CURLPIPE_HTTP1 is deprecated, and is no longer supported as of cURL
     7.62.0.
+  . The $version parameter of curl_version() is deprecated. If any value not
+    equal to the default CURLVERSION_NOW is passed, a warning is raised and the
+    parameter is ignored.
 
 - Date:
   . Calling var_dump() or similar on a DateTime(Immutable) instance will no
diff --git a/ext/curl/interface.c b/ext/curl/interface.c
@@ -1830,14 +1830,20 @@ static void curl_free_slist(zval *el)
 PHP_FUNCTION(curl_version)
 {
 	curl_version_info_data *d;
-	zend_long uversion = CURLVERSION_NOW;
+	zend_long uversion = -1;
 
 	ZEND_PARSE_PARAMETERS_START(0, 1)
 		Z_PARAM_OPTIONAL
 		Z_PARAM_LONG(uversion)
 	ZEND_PARSE_PARAMETERS_END();
 
-	d = curl_version_info(uversion);
+	if (uversion == CURLVERSION_NOW) {
+		php_error_docref(NULL, E_DEPRECATED, "the $version parameter is deprecated");
+	} else if (ZEND_NUM_ARGS() > 0) {
+		php_error_docref(NULL, E_WARNING, "$version argument ignored");
+	}
+
+	d = curl_version_info(CURLVERSION_NOW);
 	if (d == NULL) {
 		RETURN_FALSE;
 	}
diff --git a/ext/curl/tests/curl_version_error_001.phpt b/ext/curl/tests/curl_version_error_001.phpt
@@ -0,0 +1,17 @@
+--TEST--
+curl_version(): error conditions
+--SKIPIF--
+<?php
+if (!extension_loaded('curl')) die('skip curl extension not available');
+?>
+--FILE--
+<?php
+curl_version(CURLVERSION_NOW);
+curl_version(0);
+?>
+===DONE===
+--EXPECTF--
+Deprecated: curl_version(): the $version parameter is deprecated in %s on line %d
+
+Warning: curl_version(): $version argument ignored in %s on line %d
+===DONE===
