rfc:readline_interactive_shell_result_function

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:readline_interactive_shell_result_function [2021/01/16 20:50] – tandrerfc:readline_interactive_shell_result_function [2021/02/03 00:39] (current) – tandre
Line 1: Line 1:
-====== PHP RFC: Configurable callback to dump results of expressions in `php -a` ====== +====== PHP RFC: Dump results of expressions in `php -a` ====== 
-  * Version: 0.1+  * Version: 0.2
   * Date: 2020-12-19   * Date: 2020-12-19
   * Author: Tyson Andre, tandre@php.net   * Author: Tyson Andre, tandre@php.net
-  * Status: Under Discussion+  * Status: Declined
   * Implementation: https://github.com/php/php-src/pull/5962/files   * Implementation: https://github.com/php/php-src/pull/5962/files
   * First Published at: https://wiki.php.net/rfc/readline_interactive_shell_result_function   * First Published at: https://wiki.php.net/rfc/readline_interactive_shell_result_function
Line 14: Line 14:
 (I've seen https://github.com/bobthecow/psysh mentioned as an alternative for ''php -a'' while investigating this, but that's a shell written from scratch, and doesn't have some functionality from ''php -a'' such as tolerance of fatal errors) (I've seen https://github.com/bobthecow/psysh mentioned as an alternative for ''php -a'' while investigating this, but that's a shell written from scratch, and doesn't have some functionality from ''php -a'' such as tolerance of fatal errors)
  
-Because PHP's interactive shell is written in C, adding new features or bug fixes would require a lot of time getting familiar with 
-C programming, PHP's internals and memory management, and with PHP's internal C ast representation. It would be easier and more accessible to extend PHP's interactive shell through code written in PHP rather than code written in C. 
  
 ===== Proposal ===== ===== Proposal =====
Line 22: Line 20:
 Additionally, add a new function ''readline_interactive_shell_result_function'' to the ''readline'' PHP module. This function only affects interactive shells - it can be used to set or clear a closure when ''extension_loaded('readline') === true'', but that closure would only be called in interactive shells (i.e. ''php -a''). Additionally, add a new function ''readline_interactive_shell_result_function'' to the ''readline'' PHP module. This function only affects interactive shells - it can be used to set or clear a closure when ''extension_loaded('readline') === true'', but that closure would only be called in interactive shells (i.e. ''php -a'').
  
-This will dump the results of expressions every time a statement containing a single expression such as ''2+2;'' or ''$x = call_function();'' is evaluated (but not non-expressions such as ''class X{}'' or combinations of expressions such as ''$x = 1; $y = $x*2;''.+This will dump the results of expressions every time a statement containing a single expression such as ''2+2;'' or ''$x = call_function();'' is evaluated (but not non-expressions such as ''class X{}'', statement blocks such as ''{ $x = 1; }'', or combinations of expressions such as ''$x = 1; $y = $x*2;''.
  
 An example of the behavior of the default expression dumper is below: An example of the behavior of the default expression dumper is below:
Line 78: Line 76:
 newline not automatically appended by shell newline not automatically appended by shell
 => 44 => 44
-php > { print("test\n"); }; // statement blocks can be used to avoid dumping expression results+php > { print("test\n"); } // statement blocks can be used to avoid dumping expression results
 test test
 php > php >
Line 86: Line 84:
  
 <code php> <code php>
-php -a+$ php -a
 Interactive shell Interactive shell
  
Line 120: Line 118:
  */  */
 function readline_interactive_shell_result_function(?callable $callback): bool; function readline_interactive_shell_result_function(?callable $callback): bool;
 +</code>
 +
 +The default implementation added as part of this RFC is effectively identical to the below implementation, but written in C. It can be replaced with a userland implementation or disabled at any time, even in [[https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file|auto_prepend_file]]. (Because the default implementation is written in C, it will work even if the ini setting ''disable_functions'' includes var_dump and var_export.)
 +
 +<code php>
 +readline_interactive_shell_result_function(
 +    function(string $code, $result) {
 +        if (!isset($result)) {
 +            return;
 +        }
 +        if (is_scalar($result)) {
 +            echo "=> " . var_export($result, true) . "\n";
 +        } else {
 +            echo "=> "; var_dump($result);
 +        }});
 </code> </code>
  
Line 125: Line 138:
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-None, only interactive sessions are affected, and only when this functionality is enabled and a callback is installed.+ 
 +Only interactive sessions (''php -a'') are affected, by a difference in the output sent to stdout. The dumping of expression results can be disabled entirely with the ini setting ''cli.enable_interactive_shell_result_function = Off'', or temporarily by calling ''readline_interactive_shell_result_function(null)'' 
 + 
 +In interactive sessions, this will start calling [[https://www.php.net/manual/en/language.oop5.magic.php#object.debuginfo|__debugInfo()]] if it exists due to calling ''var_dump()'' on objects. Implementations of ''__debugInfo()'' may throw or have other side effects after the expression is evaluated. 
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 162: Line 179:
   * i.e. change ''foo(); bar();'' to ''foo(); return (bar());''   * i.e. change ''foo(); bar();'' to ''foo(); return (bar());''
  
-===== Proposed Voting Choices =====+==== Rendering a result limit ====
  
-Voting starts on 2021-01-03 and ends 2021-01-17.+https://externals.io/message/112934#113039 was brought up after the start of the vote. While some REPLs don't limit results, others do, and it's useful to have for extremely large objects. 
 +The setting ''cli.pager'' can be used to limit results, but is disabled by default. 
 + 
 +<blockquote> 
 +My main concern in this iteration of the RFC is: what happens with big/deeply nested objects? 
 +They tend to spew tons of lines if var_dump()'ed. Do we have reasonable depth/output limitations in default dumping mode? 
 + 
 +I'm often enough using php -a to do some quick ad-hoc processing (example, read a big json file, and then access a value; instantiating a mediawiki bot framework and calling replace on it; ...). 
 + 
 +It's really cool to have any interactive feedback at all, but please, at least by default, limit the output. (An example is the JS REPL in browser console - it shows you a minimal preview of the object, and then you can expand with your mouse. Obviously with a pure cli application, this needs different - intuitive - navigation.) 
 + 
 +As it currently stands, this makes ''php -a'' unusable in any but the simplest cases, without just disabling the whole feature. 
 + 
 +I like the whole feature, but the missing output limitation (I have yet enough nightmares from var_dump()'ing the wrong object filling my shell with tons of irrelevant information… I don't need that potentially happening on every single evaluated expression) 
 + 
 +Thus I'm voting no, for now. 
 +</blockquote> 
 +===== Vote ===== 
 + 
 +Voting starts on 2021-01-19 and ended 2021-02-02
  
 Yes/No, requiring 2/3 majority Yes/No, requiring 2/3 majority
 +
 +<doodle title="Dump results of expressions in `php -a` as described in this RFC" auth="tandre" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== References ===== ===== References =====
  
 +  * https://externals.io/message/112568 "[RFC] Configurable callback to dump results of expressions in `php -a`"
   * https://externals.io/message/111073 "Improving the usability of PHP's interactive shell? (completions, displaying expression results, custom syntax)"   * https://externals.io/message/111073 "Improving the usability of PHP's interactive shell? (completions, displaying expression results, custom syntax)"
-  * https://wiki.php.net/rfc/readline_interactive_shell_result_function_straw_poll+  * https://wiki.php.net/rfc/readline_interactive_shell_result_function_straw_poll "Straw poll: Interest in configurable callback to dump results of expressions in ''php -a''" 
 + 
 +===== Changelog ===== 
 + 
 +0.2: Dump non-null expression results by default with var_dump()/var_export() 
 +0.3: Document the default implementation used in the implementation
rfc/readline_interactive_shell_result_function.1610830240.txt.gz · Last modified: 2021/01/16 20:50 by tandre

Page Tools