Interactive shell documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@299580 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Daniel Egeberg 2010-05-21 14:05:13 +00:00
parent 5e05b9d6ea
commit 20b6ea33c7

View file

@ -366,29 +366,10 @@ Usage: php [options] [-f] <file> [--] [args...]
<entry>--interactive</entry>
<entry>
<para>
Runs PHP interactively. If you compile PHP with the <link
linkend="ref.readline">Readline</link> extension (which is not
available on Windows), you'll have a nice shell, including a
completion feature (e.g. you can start typing a variable name, hit the
TAB key and PHP completes its name) and a typing history that can be
accessed using the arrow keys. The history is saved in the
<filename>~/.php_history</filename> file.
Runs PHP interactively. For more information, see the <link
linkend="features.commandline.interactive">Interactive shell</link>
section.
</para>
<note>
<para>
Files included through <link
linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
linkend="ini.auto-append-file">auto_append_file</link> are parsed in
this mode but with some restrictions - e.g. functions have to be
defined before called.
</para>
</note>
<note>
<para>
<link linkend="language.oop5.autoload">Autoloading</link> is not
available if using PHP in &cli; interactive mode.
</para>
</note>
</entry>
</row>
<row>
@ -1389,6 +1370,159 @@ php -r 'fwrite(STDERR, "stderr\n");'
</note>
</section>
<!--}}}-->
<!--Interactive shell: {{{-->
<section xml:id="features.commandline.interactive">
<title>Interactive shell</title>
<para>
As of PHP 5.1.0, the &cli.sapi; provides an interactive shell using the
<option>-a</option> option if PHP is compiled with the <option
role="configure">--with-readline</option> option.
</para>
<para>
Using the interactive shell you are able to type PHP code and have it
executed directly.
</para>
<example>
<title>Executing code using the interactive shell</title>
<programlisting role="shell">
<![CDATA[
$ php -a
Interactive shell
php > echo 5+8;
13
php > function addTwo($n)
php > {
php { return $n + 2;
php { }
php > var_dump(addtwo(2));
int(4)
php >
]]>
</programlisting>
</example>
<para>
The interactive shell also features tab completion for functions,
constants, class names, variables, static method calls and class
constants.
</para>
<example>
<title>Tab completion</title>
<simpara>
Pressing the tab key twice when there are multiple possible completions
will result in a list of these completions:
</simpara>
<programlisting role="shell">
<![CDATA[
php > strp[TAB][TAB]
strpbrk strpos strptime
php > strp
]]>
</programlisting>
<simpara>
When there is only one possible completion, pressing tab once will
complete the rest on the same line:
</simpara>
<programlisting role="shell">
<![CDATA[
php > strpt[TAB]ime(
]]>
</programlisting>
<simpara>
It is also possible doing completion on things that have been defined
during the interactive shell session:
</simpara>
<programlisting role="shell">
<![CDATA[
php > $fooThisIsAReallyLongVariableName = 42;
php > $foo[TAB]ThisIsAReallyLongVariableName
]]>
</programlisting>
</example>
<para>
The interactive shell stores your history and can be accessed using the up
and down keys. The history is saved in the
<filename>~/.php_history</filename> file.
</para>
<!-- NOT YET AVAILABLE, UNCOMMENT AND FIX VERSIONS WHEN RELEASED
<para>
As of [whatever becomes the next version], the &cli.sapi; provides
two new &php.ini; settings: <parameter>cli.pager</parameter> and
<parameter>cli.prompt</parameter>. The <parameter>cli.pager</parameter>
setting allows an external program (such as <filename>less</filename>) to
act as a pager for the output instead of being displayed directly on the
screen. The <parameter>cli.prompt</parameter> setting makes it possible to
change the <literal>php &gt;</literal> prompt.
</para>
<para>
In [whatever becoems the next version] it was also made possible setting
&php.ini; settings in the interactive shell using a shorthand notation.
</para>
<example>
<title>Setting &php.ini; settings in the interactive shell</title>
<simpara>
The <parameter>cli.prompt</parameter> setting:
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.prompt=hello world :>
hello world :>
]]>
</programlisting>
<simpara>
Using backticks it is possible to have PHP code executed in the prompt:
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.prompt=`echo date('H:i:s');` php >
15:49:35 php > echo 'hi';
hi
15:49:43 php > sleep(2);
15:49:45 php >
]]>
</programlisting>
<simpara>
Setting the pager to <filename>less</filename>:
</simpara>
<programlisting role="shell">
<![CDATA[
php > #cli.pager=less
php > phpinfo();
(output displayed in less)
php >
]]>
</programlisting>
</example>
-->
<note>
<para>
Files included through <link
linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
linkend="ini.auto-append-file">auto_append_file</link> are parsed in
this mode but with some restrictions - e.g. functions have to be
defined before called.
</para>
</note>
<note>
<para>
<link linkend="language.oop5.autoload">Autoloading</link> is not
available if using PHP in &cli; interactive mode.
</para>
</note>
</section>
<!--}}}-->
</chapter>
@ -1408,7 +1542,7 @@ sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim600: syn=xml fen fdm=marker fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->