Deprecate and ignore $version parameter of curl_version()

`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
index 7efc39f44251ef2929190bae04c85e380c2d113c..8ef4d15e2be5aed7c6e6ee00439b3504acb754fc 100644 (file)
--- 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
index f9ed09152deb246bb297f1a447bf6e2c8bc8003d..de5f1dd5a19aa3687d743eaabccb83b9d160d680 100644 (file)
--- 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
index fdf855278eef6f32f26c49b54f56aca9bd7007c3..8f695d339c1eb5142b1d1249e94db490deed0a95 100644 (file)
--- 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
new file mode 100644 (file)
index 0000000..2c56e0a
--- /dev/null
+++ 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===