features/commandline.xml
74ba8fee2972b6ba4f955392d760dea54e757a95
74ba8fee2972b6ba4f955392d760dea54e757a95
...
...
@@ -5,7 +5,7 @@
5
5
<titleabbrev>Command line usage</titleabbrev>
6
6
7
7
<!--Introduction: {{{-->
8
-
<section xml:id="features.commandline.introduction">
8
+
<section xml:id="features.commandline.introduction" annotations="chunk:false">
9
9
<title>Introduction</title>
10
10
11
11
<para>
...
...
@@ -36,7 +36,7 @@
36
36
<option role="configure">--disable-cgi</option> option is used, the &cli; is
37
37
copied to <filename>{PREFIX}/bin/php</filename> during
38
38
<command>make install</command> otherwise the <acronym>CGI</acronym> is placed
39
-
there. So, for example, if <option role="configure">--with-apxs </option> is
39
+
there. So, for example, if <option role="configure">--with-apxs</option> is
40
40
in your configure line then the &cli; is copied to <filename>{PREFIX}/bin/php
41
41
</filename> during <command>make install</command>. If you want to override
42
42
the installation of the <acronym>CGI</acronym> binary, use <command>make
...
...
@@ -182,6 +182,27 @@
182
182
also be found in the <varname>$_SERVER</varname> array, for example:
183
183
<varname>$_SERVER['argv']</varname>.
184
184
</para>
185
+
<warning>
186
+
<para>
187
+
The presence of <varname>$argv</varname> or <varname>$_SERVER['argv']</varname>
188
+
is not a reliable indication that a script is being run from the
189
+
command line because they may be set in other contexts when
190
+
<link linkend="ini.register-argc-argv">register_argc_argv</link> is enabled.
191
+
The value returned by <function>php_sapi_name</function> should be checked
192
+
instead.
193
+
<informalexample>
194
+
<programlisting role="php">
195
+
<![CDATA[
196
+
<?php
197
+
198
+
if (php_sapi_name() === 'cli') {
199
+
echo "This is being run from the command line!\n";
200
+
}
201
+
]]>
202
+
</programlisting>
203
+
</informalexample>
204
+
</para>
205
+
</warning>
185
206
</entry>
186
207
</row>
187
208
<row>
...
...
@@ -462,6 +483,7 @@ $ php -c /custom/directory/custom-file.ini my_script.php
462
483
</screen>
463
484
</para>
464
485
<para><example>
486
+
<title>Example of using <literal>-d</literal> to set an INI setting</title>
465
487
<screen>
466
488
<![CDATA[
467
489
# Omitting the value part will set the given configuration directive to "1"
...
...
@@ -506,13 +528,6 @@ string(15) "doesntmakesense"
506
528
<option>-f</option> is optional and may be omitted - providing just
507
529
the filename to execute is sufficient.
508
530
</para>
509
-
<note>
510
-
<para>
511
-
To pass arguments to a script, the first argument must be
512
-
<literal>--</literal>, otherwise PHP will interpret them as PHP
513
-
options.
514
-
</para>
515
-
</note>
516
531
</entry>
517
532
</row>
518
533
<row>
...
...
@@ -540,19 +555,28 @@ string(15) "doesntmakesense"
540
555
<entry>--syntax-check</entry>
541
556
<entry>
542
557
<para>
543
-
Provides a convenient way to perform only a syntax check
544
-
on the given PHP code. On success, the text
558
+
Syntax check but do not execute the given PHP code.
559
+
The input from standard input will be processed if no filenames are specified,
560
+
otherwise each filename will be checked.
561
+
On success, the text
545
562
<literal>No syntax errors detected in <filename></literal> is
546
-
written to standard output and the shell return code is
547
-
<literal>0</literal>. On failure, the text <literal>Errors parsing
548
-
<filename></literal> in addition to the internal parser error
549
-
message is written to standard output and the shell return code is set
550
-
to <literal>-1</literal>.
563
+
written to standard output.
564
+
On failure, the text <literal>Errors parsing <filename></literal>
565
+
is written to standard output in addition to the internal parser error.
566
+
If any failures are found in the specified files (or standard input),
567
+
the shell return code is set to <literal>-1</literal>, otherwise the
568
+
shell return code is set to <literal>0</literal>.
551
569
</para>
552
570
<para>
553
-
This option won't find fatal errors (like undefined functions). Use
554
-
the <option>-f</option> to test for fatal errors too.
571
+
This option won't find fatal errors (like undefined functions) that
572
+
require executing the code.
555
573
</para>
574
+
<note>
575
+
<para>
576
+
Prior to PHP 8.3.0, it was only possible to specify one filename to
577
+
be checked.
578
+
</para>
579
+
</note>
556
580
<note>
557
581
<para>
558
582
This option does not work together with the <option>-r</option>
...
...
@@ -1046,12 +1070,6 @@ $ php -f my_script.php
1046
1070
restriction on which files can be executed; in particular, the filename
1047
1071
is not required have a <literal>.php</literal> extension.
1048
1072
</para>
1049
-
<note>
1050
-
<para>
1051
-
If arguments need to be passed to the script when using
1052
-
<option>-f</option>, the first argument must be <literal>--</literal>.
1053
-
</para>
1054
-
</note>
1055
1073
</listitem>
1056
1074
<listitem>
1057
1075
<para>
...
...
@@ -1107,8 +1125,8 @@ $ some_application | some_filter | php | sort -u > final_output.txt
1107
1125
first index (zero) always contains the name of the script as called from the
1108
1126
command line. Note that, if the code is executed in-line using the command
1109
1127
line switch <option>-r</option>, the value of <varname>$argv[0]</varname>
1110
-
will be just a dash (<literal>-</literal>). The same is true if the code is
1111
-
executed via a pipe from <literal>STDIN</literal>.
1128
+
will be <literal>"Standard input code"</literal>; prior to PHP 7.2.0, it was a dash (<literal>"-"</literal>) instead. The same is true if the code is
1129
+
executed via a pipe from <constant>STDIN</constant>.
1112
1130
</para>
1113
1131
1114
1132
<para>
...
...
@@ -1264,7 +1282,7 @@ This is a command line PHP script with one option.
1264
1282
<para>
1265
1283
<example>
1266
1284
<title>Batch file to run a command line PHP script (script.bat)</title>
1267
-
<programlisting role="shell">
1285
+
<programlisting role="winbat">
1268
1286
<![CDATA[
1269
1287
@echo OFF
1270
1288
"C:\php\php.exe" script.php %*
...
...
@@ -1289,7 +1307,7 @@ This is a command line PHP script with one option.
1289
1307
<para>
1290
1308
On Windows, PHP can be configured to run without the need to
1291
1309
supply the <filename>C:\php\php.exe</filename> or the <literal>.php</literal>
1292
-
extension, as described in <link linkend="install.windows.legacy.commandline">Command
1310
+
extension, as described in <link linkend="install.windows.commandline">Command
1293
1311
Line PHP on Microsoft Windows</link>.
1294
1312
</para>
1295
1313
...
...
@@ -1482,11 +1500,13 @@ php > $foo[TAB]ThisIsAReallyLongVariableName
1482
1500
</programlisting>
1483
1501
</example>
1484
1502
1485
-
<para>
1503
+
<simpara>
1486
1504
The interactive shell stores your history which can be accessed using the up
1487
1505
and down keys. The history is saved in the
1488
1506
<filename>~/.php_history</filename> file.
1489
-
</para>
1507
+
As of PHP 8.4.0, the path to the history file can be set using the
1508
+
<envar>PHP_HISTFILE</envar> environment variable.
1509
+
</simpara>
1490
1510
1491
1511
<para>
1492
1512
The &cli.sapi; provides
...
...
@@ -1594,6 +1614,32 @@ php >
1594
1614
defined before called.
1595
1615
</para>
1596
1616
</note>
1617
+
1618
+
<section xml:id="features.commandline.interactive.mode">
1619
+
<title>Interactive mode</title>
1620
+
<para>
1621
+
If the readline extension is not available, prior to PHP 8.1.0, invoking the &cli.sapi; with the
1622
+
<option>-a</option> option provided the interactive mode. In this mode, a
1623
+
complete PHP script is supposed to be given via STDIN, and after termination
1624
+
with
1625
+
<keycombo action='simul'>
1626
+
<keycap>CTRL</keycap>
1627
+
<keycap>D</keycap>
1628
+
</keycombo>
1629
+
(POSIX) or
1630
+
<keycombo action='simul'>
1631
+
<keycap>CTRL</keycap>
1632
+
<keycap>Z</keycap>
1633
+
</keycombo>
1634
+
followed by <keycap>ENTER</keycap> (Windows), this script is evaluated.
1635
+
This is basically the same as invoking the &cli.sapi; without the <option>-a</option>
1636
+
option.
1637
+
</para>
1638
+
<para>
1639
+
As of PHP 8.1.0, invoking the &cli.sapi; with the <option>-a</option> option
1640
+
fails, if the readline extension is not available.
1641
+
</para>
1642
+
</section>
1597
1643
</section>
1598
1644
<!--}}}-->
1599
1645
...
...
@@ -1640,95 +1686,82 @@ php >
1640
1686
</para>
1641
1687
1642
1688
<para>
1643
-
Standard MIME types are returned for files with extensions: .3gp,
1644
-
.apk, .avi, .bmp, .css, .csv, .doc, .docx, .flac, .gif, .gz,
1645
-
.gzip, .htm, .html, .ics, .jpe, .jpeg, .jpg, .js, .kml, .kmz,
1646
-
.m4a, .mov, .mp3, .mp4, .mpeg, .mpg, .odp, .ods, .odt, .oga, .ogg,
1647
-
.ogv, .pdf, .pdf, .png, .pps, .pptx, .qt, .svg, .swf, .tar, .text,
1648
-
.tif, .txt, .wav, .webm, .wmv, .xls, .xlsx, .xml, .xsl, .xsd, and .zip.
1689
+
Standard MIME types are returned for files with extensions:
1690
+
<simplelist type="inline">
1691
+
<member><literal>.3gp</literal></member>
1692
+
<member><literal>.apk</literal></member>
1693
+
<member><literal>.avi</literal></member>
1694
+
<member><literal>.bmp</literal></member>
1695
+
<member><literal>.css</literal></member>
1696
+
<member><literal>.csv</literal></member>
1697
+
<member><literal>.doc</literal></member>
1698
+
<member><literal>.docx</literal></member>
1699
+
<member><literal>.flac</literal></member>
1700
+
<member><literal>.gif</literal></member>
1701
+
<member><literal>.gz</literal></member>
1702
+
<member><literal>.gzip</literal></member>
1703
+
<member><literal>.htm</literal></member>
1704
+
<member><literal>.html</literal></member>
1705
+
<member><literal>.ics</literal></member>
1706
+
<member><literal>.jpe</literal></member>
1707
+
<member><literal>.jpeg</literal></member>
1708
+
<member><literal>.jpg</literal></member>
1709
+
<member><literal>.js</literal></member>
1710
+
<member><literal>.kml</literal></member>
1711
+
<member><literal>.kmz</literal></member>
1712
+
<member><literal>.m4a</literal></member>
1713
+
<member><literal>.mov</literal></member>
1714
+
<member><literal>.mp3</literal></member>
1715
+
<member><literal>.mp4</literal></member>
1716
+
<member><literal>.mpeg</literal></member>
1717
+
<member><literal>.mpg</literal></member>
1718
+
<member><literal>.odp</literal></member>
1719
+
<member><literal>.ods</literal></member>
1720
+
<member><literal>.odt</literal></member>
1721
+
<member><literal>.oga</literal></member>
1722
+
<member><literal>.ogg</literal></member>
1723
+
<member><literal>.ogv</literal></member>
1724
+
<member><literal>.pdf</literal></member>
1725
+
<member><literal>.png</literal></member>
1726
+
<member><literal>.pps</literal></member>
1727
+
<member><literal>.pptx</literal></member>
1728
+
<member><literal>.qt</literal></member>
1729
+
<member><literal>.svg</literal></member>
1730
+
<member><literal>.swf</literal></member>
1731
+
<member><literal>.tar</literal></member>
1732
+
<member><literal>.text</literal></member>
1733
+
<member><literal>.tif</literal></member>
1734
+
<member><literal>.txt</literal></member>
1735
+
<member><literal>.wav</literal></member>
1736
+
<member><literal>.webm</literal></member>
1737
+
<member><literal>.wmv</literal></member>
1738
+
<member><literal>.xls</literal></member>
1739
+
<member><literal>.xlsx</literal></member>
1740
+
<member><literal>.xml</literal></member>
1741
+
<member><literal>.xsl</literal></member>
1742
+
<member><literal>.xsd</literal></member>
1743
+
<member><literal>.zip</literal></member>
1744
+
</simplelist>
1745
+
.
1649
1746
</para>
1650
1747
1651
-
1652
-
<table>
1653
-
<title>Changelog: Supported MIME Types (file extensions)</title>
1654
-
<tgroup cols="2">
1655
-
<thead>
1656
-
<row>
1657
-
<entry>&Version;</entry>
1658
-
<entry>&Description;</entry>
1659
-
</row>
1660
-
</thead>
1661
-
<tbody>
1662
-
<row>
1663
-
<entry>5.5.12</entry>
1664
-
<entry>
1665
-
.xml, .xsl, and .xsd
1666
-
</entry>
1667
-
</row>
1668
-
<row>
1669
-
<entry>5.5.7</entry>
1670
-
<entry>
1671
-
.3gp, .apk, .avi, .bmp, .csv, .doc, .docx, .flac, .gz, .gzip,
1672
-
.ics, .kml, .kmz, .m4a, .mp3, .mp4, .mpg, .mpeg, .mov, .odp, .ods,
1673
-
.odt, .oga, .pdf, .pptx, .pps, .qt, .swf, .tar, .text, .tif, .wav,
1674
-
.wmv, .xls, .xlsx, and .zip
1675
-
</entry>
1676
-
</row>
1677
-
<row>
1678
-
<entry>5.5.5</entry>
1679
-
<entry>
1680
-
.pdf
1681
-
</entry>
1682
-
</row>
1683
-
<row>
1684
-
<entry>5.4.11</entry>
1685
-
<entry>
1686
-
.ogg, .ogv, and .webm
1687
-
</entry>
1688
-
</row>
1689
-
<row>
1690
-
<entry>5.4.4</entry>
1691
-
<entry>
1692
-
.htm and .svg
1693
-
</entry>
1694
-
</row>
1695
-
</tbody>
1696
-
</tgroup>
1697
-
</table>
1698
-
1699
-
1700
-
<table>
1701
-
<title>Changelog</title>
1702
-
<tgroup cols="2">
1703
-
<thead>
1704
-
<row>
1705
-
<entry>&Version;</entry>
1706
-
<entry>&Description;</entry>
1707
-
</row>
1708
-
</thead>
1709
-
<tbody>
1710
-
<row>
1711
-
<entry>7.4.0</entry>
1712
-
<entry>
1713
-
You can configure the built-in webserver to fork multiple workers
1714
-
in order to test code that requires multiple concurrent requests to
1715
-
the built-in webserver. Set the <envar>PHP_CLI_SERVER_WORKERS</envar>
1716
-
environment variable to the number of desired workers before starting
1717
-
the server.
1718
-
This is not supported on Windows.
1719
-
<warning>
1720
-
<para>
1721
-
This <emphasis>experimental</emphasis> feature is <emphasis>not</emphasis>
1722
-
intended for production usage. Generally, the built-in Web Server is
1723
-
<emphasis>not</emphasis> intended for production usage.
1724
-
</para>
1725
-
</warning>
1726
-
</entry>
1727
-
</row>
1728
-
</tbody>
1729
-
</tgroup>
1730
-
</table>
1731
-
1748
+
<simpara>
1749
+
As of PHP 7.4.0, the built-in webserver can be configured to fork multiple
1750
+
workers in order to test code that requires multiple concurrent requests
1751
+
to the built-in webserver.
1752
+
Set the <envar>PHP_CLI_SERVER_WORKERS</envar> environment variable to the
1753
+
number of desired workers before starting the server.
1754
+
</simpara>
1755
+
<note>
1756
+
<simpara>This feature is not supported on Windows.</simpara>
1757
+
</note>
1758
+
<warning>
1759
+
<para>
1760
+
This <emphasis>experimental</emphasis> feature is <emphasis>not</emphasis>
1761
+
intended for production usage. Generally, the built-in Web Server is
1762
+
<emphasis>not</emphasis> intended for production usage.
1763
+
</para>
1764
+
</warning>
1732
1765
1733
1766
<example>
1734
1767
<title>Starting the web server</title>
...
...
@@ -1903,7 +1936,7 @@ $ php -S 0.0.0.0:8000
1903
1936
<row>
1904
1937
<entry><link linkend="ini.cli-server.color">cli_server.color</link></entry>
1905
1938
<entry>"0"</entry>
1906
-
<entry>PHP_INI_ALL</entry>
1939
+
<entry><constant>INI_ALL</constant></entry>
1907
1940
<entry></entry>
1908
1941
</row>
1909
1942
</tbody>
1910
1943