====== PHP RFC: Add an optional parameter $result_code to shell_exec() ======
  * Version: 1
  * Date: 2021-11-21
  * Author: Luca Petrucci, luca@lucapetrucci.net
  * Status: Under discussion
  * First Published at: http://wiki.php.net/rfc/shell_exec_result_code_param

===== Introduction =====
The shell_exec() function is used to execute an external program and grab its entire output as a string, but it lacks a way to capture the exit code of the launched program contrarily to all the other functions of the same family (exec, system, passthru).

===== Proposal =====
This RFC proposes the addition of a second, optional parameter $result_code to the shell_exec() function:
<code php> function shell_exec(string $command, &$result_code = null): string|false|null {} </code>
If $result_code is present, the function will put the return code of the program into it. The same parameter and behaviour is found in exec(), system() and passthru() functions.


===== Backward Incompatible Changes =====
No backward compatibility breaks.

===== Proposed PHP Version(s) =====
Next PHP 8.x, currently PHP 8.2.

===== RFC Impact =====
==== To SAPIs ====
None.

==== To Existing Extensions ====
None.

==== To Opcache ====
None.

==== New Constants ====
No new constants introduced.

==== php.ini Defaults ====
No new php.ini options introduced.

===== Unaffected PHP Functionality =====
  * Behaviour of shell_exec() when called with one parameter will not change;
  * [[https://www.php.net/manual/en/language.operators.execution.php|Backtick operator]] functionality is unaffected.

===== Proposed Voting Choices =====
Yes/No vote, super majority of 2/3 required to pass.

===== Implementation =====
  * [[https://github.com/php/php-src/pull/7663|Pull request (Github)]]

===== References =====
  * [[https://bugs.php.net/bug.php?id=81493|Relevant feature request posted by another user (Bugsnet)]]
  * Functions that already have the return_code parameter:
    * [[https://www.php.net/manual/en/function.exec.php|exec()]]
    * [[https://www.php.net/manual/en/function.system.php|system()]]
    * [[https://www.php.net/manual/en/function.passthru.php|passthru()]]