php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #80230 Doc for exec specifies & (reference) param, fails
Submitted: 2020-10-13 19:45 UTC Modified: 2020-10-13 20:28 UTC
From: per at perit dot se Assigned:
Status: Verified Package: Documentation problem
PHP Version: Irrelevant OS: Linux
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: per at perit dot se
New email:
PHP Version: OS:

 

 [2020-10-13 19:45 UTC] per at perit dot se
Description:
------------
---
From manual page: https://php.net/function.exec
---
The documentation specifies syntax
exec ( string $command [, array &$output [, int &$return_var ]] ) : string

This syntax breaks PHP, and according to numerous internet articles like https://stackoverflow.com/questions/8971261/php-5-4-call-time-pass-by-reference-easy-fix-available explaining it has been so a while:
> As of PHP 5.3.0, you will get a warning saying that "call-time pass-by-reference" is deprecated when you use & in foo(&$a);.

Please update the documentation with correct syntax, and if/when it differs for specific versions, please note the version and change in question - now it incorrectly claims to be valid for "(PHP 4, PHP 5, PHP 7)"



Test script:
---------------
$ cat > test-ref-arg.php
<?php
  exec ( "pwd", &$output );  
  echo "Got output: ";
  var_dump($output);

$ php test-ref-arg.php
PHP Fatal error:  Call-time pass-by-reference has been removed in /home/xx/IMPORT/test-ref-arg on line 2

/opt/rh/rh-php73/root/bin/php test-ref-arg.php
PHP Parse error:  syntax error, unexpected '&', expecting ')' in /home/xx/test-ref-arg.php on line 2



Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-10-13 20:04 UTC] rowan dot collins at gmail dot com
The documentation is showing you the *signature* of the function, not the *usage*. An actual declaration in userland would in fact look something like this:

function exec (string $command, ?array &$output=null, ?int &$return_var=null): string { .... }

The manual page could do with an example of using those params though, which would look something like this:

$output=null;
$retval=null;
exec('whoami', $output, $retval);
echo "Returned with status $retval and output $output";
 [2020-10-13 20:28 UTC] cmb@php.net
-Status: Open +Status: Verified
 [2020-10-13 20:28 UTC] cmb@php.net
What Rowan said.  And yes, there should be an example.

Note that there is also an appendix on "How to read a function
definition (prototype)"[1]

> "(PHP 4, PHP 5, PHP 7)"

That just means that function is available for PHP 4, 5 and 7; it
does not imply that it worked exactly the same in older versions.
In fact, the manual currently is supposed to document only PHP 7
(there is few info about PHP 8, and still some info about PHP 5,
though).

[1] <https://www.php.net/manual/en/about.prototypes.php>
 
PHP Copyright © 2001-2020 The PHP Group
All rights reserved.
Last updated: Mon Nov 23 19:01:26 2020 UTC