Manuals > PHP > PHP auf der Kommandozeile

Kapitel 23. PHP auf der Kommandozeile

Seit Version 4.3.0 unterstützt PHP einen neuen Typ SAPI (Server Application Programming Interface) namens CLI (Command Line Interface). Wie der Name schon verrät, liegt das Hauptaugemerk dieses SAPI-Typs auf der Entwicklung von Anwendungen für die Kommandozeile (und auch den Desktop) mit PHP. Es gibt etliche Unterschiede zwischen dem CLI SAPI und anderen SAPIs, die in diesem Kapitel beschrieben werden. Es ist erwähnenswert, dass CLI und CGI verschiedene SAPIs sind, obwohl sie viele Verhaltensweisen teilen.

Das CLI SAPI wurde zum ersten Mal mit PHP 4.2.0 eingeführt, war aber noch experimentell und musste explizit mit --enable-cli beim ./configure-Aufruf eingeschaltet werden. Seit PHP 4.3.0 ist das CLI SAPI nicht länger experimentell und die Option --enable-cli standardmäßig auf on gestellt. Sie können --disable-cli benutzen, um es auszuschalten.

Von PHP 4.3.0 an werden Namen, Pfade und Vorhandensein der CLI/CGI-Binaries voneinander abweichen, abhängig davon, wie PHP auf Ihrem System installiert ist. Standarmäßig werden nach dem Aufruf von make sowohl CGI als auch CLI kompiliert und als sapi/cgi/php beziehungsweise sapi/cli/php in Ihrem PHP-Quellcodeverzeichnis hinterlegt. Sie werden bemerken, dass beide php benannt sind. Was während make install passiert, hängt von Ihrem configure-Kommando ab. Wenn ein Modul-SAPI während configure gewählt wird, wie etwa apxs oder wenn die --disable-cgi-Option benutzt wird, wird das CLI während make install nach /bin/php kopiert, ansonsten wird das CGI dort hinterlegt. Also wird, wenn beispielsweise --with--apxs in Ihrem configure-Kommando auftaucht, das CLI während make install nach /bin/php kopiert. Wenn Sie die Installation des CGI-Binaries außer Kraft setzen wollen, benutzen Sie make install-cli nach make install. Alternativ können Sie --disable-cgi in Ihrem configure-Kommando angeben.

Die Windows-Pakete zwischen PHP 4.2.0 und PHP 4.2.3 enthielten das CLI als php-cli.exe, beheimatet im selben Verzeichnis wie das CGI php.exe. Beginnend mit PHP 4.3.0 enthält das Windows-Paket das CLI als php.exe in einem eigenen Verzeichnis namens cli, also cli/php.exe.

Beachtenswerte Unterschiede des CLI SAPI verglichen mit anderen SAPIs:

• Anders als beim CGI SAPI werden keine Header ausgegeben.

  Obwohl das CGI SAPI einen Weg bietet, HTTP-Header zu unterdrücken, gibt es keine gleichwertige Option, sie im CLI SAPI anzuzeigen.

  CLI wird standardmäßig im stillen Modus gestartet, dennoch gibt es die -q-Option aus Kompatibilitätsgründen noch, so dass Sie auch ältere CGI-Skripte noch benutzen können.

  Es verändert das Arbeitsverzeichnis nicht zu dem des Skriptes. (Die -C-Option wurde aus Kompatibilitätsgründen beibehalten)

  Fehlermeldungen in Plaintext (keine HTML-Formatierung).

• Es gibt bestimmte php.ini-Direktiven, die vom CLI SAPI außer Kraft gesetzt werden, weil sie in einer Kommandozeilenumgebung keinen Sinn ergeben.

  Tabelle 23-1. Überschriebene php.ini-Direktiven

  Direktive	CLI SAPI-Standardwert	Kommentar
  html_errors	FALSE	Es kann sehr schwierig sein, eine Fehlermeldung auf der Kommandozeile zu lesen, wenn sie mit all diesen bedeutungslosen HTML-Tags vollgestopft ist, deswegen wird diese Direktive auf FALSE gesetzt.
  implicit_flush	TRUE	Es ist erwünscht, dass alle Ausgaben, die von print(), echo() und Konsorten kommen, sofort auf die Ausgabe geschrieben werden und nicht in irgendeinem Puffer gecacht werden. Sie können immer noch output buffering benutzen, wenn Sie die Standardausgabe aufschieben oder manipulieren wollen.
  max_execution_time	0 (unlimited)	Wegen der unendlichen Möglichkeiten, PHP in Kommandozeilenumgebungen zu benutzen wurde die maximale Ausführungszeit auf unbegrenzte Zeit eingestellt. Wohingegen Anwendungen, die für das Web geschrieben wurden, oft in sehr kurzer Zeit ausgeführt werden, neigen Anwendungen für die Kommandozeile dazu, eine viel längere Ausführungszeit zu beanspruchen.
  register_argc_argv	TRUE	Weil diese Einstellung auf TRUE gesetzt ist, werden Sie immer Zugriff auf argc (Anzahl der Argumente, die der Anwendung übergeben wurden) und argv (Array der eigentlichen Argumente) im CLI SAPI haben. Seit PHP 4.3.0 werden die PHP-Variablen $argc und $argv registriert und mit den entsprechenden Werten gefüllt, wenn das CLI SAPI benutzt wird. Vor dieser Version verhielt sich die Erzeugung dieser Variablen so wie in den CGI und MODULE-Versionen, die die PHP-Direktive register_globals auf on verlangen. Ungeachtet der Version oder der Einstellung von register_globals können Sie immer $_SERVER oder $HTTP_SERVER_VARS benutzen. Beispiel: $_SERVER['argv']

  Anmerkung: Diese Direktiven können nicht mit einem anderen Wert aus der Konfigurationsdatei php.ini oder einer eigenen (falls angegeben) initialisiert werden. Das ist eine Einschränkung, weil diese Standardwerte angewandt werden, nachdem alle Konfigurationsdateien durchlaufen wurden. Dennoch können die Werte zur Laufzeit verändert werden (was aber für alle diese Direktiven keinen Sinn ergibt, beispielsweise register_argc_argv).

• Um die Arbeit in der Kommandozeilenumgebung zu vereinfachen, wurden folgende Konstanten definiert:

  Tabelle 23-2. CLI-spezifische Konstanten

  Konstante	Beschreibung
  STDIN	Ein schon geöffneter Stream auf stdin. Das erspart das öffnen mit $stdin = fopen('php://stdin', 'r');
  STDOUT	Ein schon geöffneter Stream auf stdout. Das erspart das öffnen mit $stdout = fopen('php://stdout', 'w');
  STDERR	Ein schon geöffneter Stream auf stderr. Das erspart das öffnen mit $stderr = fopen('php://stderr', 'w');

  Angesichts des oben genannten brauchen Sie beispielsweise nicht selbst einen Stream für stderr öffnen, sondern einfach die Konstante statt der Ressource:

  php -r 'fwrite(STDERR, "stderr\n");'

  Sie brauchen diese Ressourcen nicht explizit schliessen, weil sie automatisch von PHP geschlossen werden, wenn ihr Skript endet.

• Das CLI SAPI ändert das aktuelle Verzeichnis nicht auf das Verzeichnis des ausgeführten Skriptes!

  Ein Beispiel, das den Unterschied zum CGI SAPI zeigt:

  <?php     /* Our simple test application named test.php*/     echo getcwd(), "\n"; ?>

  Bei der CGI-Version ist die Ausgabe folgende:

  $ pwd /tmp $ php -q another_directory/test.php /tmp/another_directory

  Dies zeigt deutlich, dass PHP das aktuelle Verzeichnis auf das des asugeführten Skriptes ändert.

  Benutzen der CLI SAPI-Version ergibt:

  $ pwd /tmp $ php -f another_directory/test.php /tmp

  Dies erlaubt eine größere Anpassungsfähigkeit beim Schreiben von Kommandozeilenanwendungen in PHP.

  Anmerkung: Das CGI SAPI unterstützt das Verhalten des CLI SAPI anhand der Option -C, wenn es auf der Kommandozeile gestartet wird.

Die Liste der Kommandozeilenoptionen, die das PHP-Binary bereitstellt, können jederzeit abgerufen werden, wenn man PHP mit der Option -h startet:

Usage: php [options] [-f] <file> [args...] php [options] -r <code> [args...] php [options] [-- args...] -s Display colour syntax highlighted source. -w Display source with stripped comments and whitespace. -f <file> Parse <file>. -v Version number -c <path>|<file> Look for php.ini file in this directory -a Run interactively -d foo[=bar] Define INI entry foo with value 'bar' -e Generate extended information for debugger/profiler -z <file> Load Zend extension <file>. -l Syntax check only (lint) -m Show compiled in modules -i PHP information -r <code> Run PHP <code> without using script tags <?..?> -h This help args... Arguments passed to script. Use -- args when first argument starts with - or script is read from stdin

Beim CLI SAPI gibt es drei verschiedene Möglichkeiten, den zur Ausführung bestimmten PHP-Code zu übergeben:

1. PHP mitteilen, eine bestimmte Datei auszuführen.

   php my_script.php php -f my_script.php

   Beide Arten (ob sie die Option -f benutzen oder nicht) führen die Datei my_script.php aus. Sie können eine beliebige Datei ausführen - Ihr PHP-Skript muss nicht die Dateiendung .php haben, sie kann einen beliebigen Namen und eine beliebige Endung haben.

2. Den PHP-Code, der ausgeführt werden soll, direkt auf der Kommandozeile übergeben.

   php -r 'print_r(get_defined_constants());'

   Bezüglich Ersetzung von Kommandozeilenvariablen und Benutzung von Quotes muss besondere Vorsicht getroffen werden.

   Anmerkung: Betrachten Sie das Beispiel sorgfältig, es sind keine Start- oder Endtags gesetzt. Die Option -r benötigt sie nicht. Werden sie dennoch verwendet, kommt es zu einem Parser-Fehler.

3. Stellen Sie den PHP-Code, der ausgeführt werden soll über den Standard-Input (stdin) bereit.

   Dies eröffnet die leistungsfähige Möglichkeit, PHP-Code dynamisch zu generieren und ihn dem PHP-Binary zu übergeben, wie in diesem möglichem Beispiel:

   $ some_application | some_filter | php | sort -u >final_output.txt

Sie können diese drei Möglichkeiten zur Ausführung nicht kombinieren.

Wie jede Kommandozeilenanwendung nimmt das PHP-Binary etliche Argumente entegegen, aber auch ein PHP-Skript kann Argumente entgegennehmen. Die Anzahl der Argumente, die an ein Skript übergeben werden können, ist nicht von PHP beschränkt (aber die Kommandozeilenumgebung hat ein bestimmtes Grössenlimit für die Anzahl der Argumente, die übergeben werden können; normalerweise werden Sie dieses Limit nicht erreichen). Die Argumente, die dem Skript übergeben werden, sind in dem globalen Array $argv gespeichert. Der Null-Index enthält immer den Skriptnamen (das bedeutet -, wenn der PHP-Code entweder von der Standardeingabe oder von der Kommandozeilenoption -r kommt). Die zweite registrierte globale Variable ist $argc, die die Anzahl der Elemente im Array $argv enthält (nicht die Anzahl Argumente, die dem Skript übergeben wurden).

Solange die Argumente, die Sie dem Skript übergeben möchten, nicht mit dem Zeichen - beginnen, gibt es nichts besonderes zu beachten. Ein Argument, das mit - beginnt zu übergeben, wird Probleme bereiten, weil PHP selbst denkt, dass sie verarbeitet werden muss. Benutzen Sie das Argument-Trennzeichen -- um das zu vermeiden. Nachdem dieses Trennzeichen von PHP geparst wurde, wird jedes folgende Argument unangetastet an das Skript weitergereicht.

# This will not execute the given code but will show the PHP usage $ php -r 'var_dump($argv);' -h Usage: php [options] [-f] <file> [args...] [...] # This will pass the '-h' argument to your script and prevent PHP from showing it's usage $ php -r 'var_dump($argv);' -- -h array(2) { [0]=> string(1) "-" [1]=> string(2) "-h" }

Dennoch gibt es einen anderen Weg, um PHP für Kommandozeilenskripte zu benutzen. Sie können ein Skript erstellen, in dem die erste Zeile mit #!/usr/bin/php beginnt. Nachfolgend können Sie normalen PHP-Code innerhalb der PHP-Start- und -End-Tags setzen. Sobald Sie die Datei ausführbar gemacht haben (beispielsweise chmod +x test), kann Ihr Skript wie ein normales Kommandozeilen- oder Perlskript gestartet werden.

#!/usr/bin/php <?php     var_dump($argv); ?>

Angenommen, die Datei heisst test und befindet sich im aktuellen Verzeichnis, dann können wir nun folgendes tun:

$ chmod 755 test $ ./test -h -- foo array(4) { [0]=> string(6) "./test" [1]=> string(2) "-h" [2]=> string(2) "--" [3]=> string(3) "foo" }

Wie Sie sehen können, müssen Sie sich in diesem Fall um nichts weiter kümmern, wenn Sie Ihrem Skript Paramater, die mit - beginnen, übergeben.

The PHP executable can be used to run PHP scripts absolutely independent from the web server. If you are on a Unix system, you should add a special first line to your PHP script, and make it executable, so the system will know, what program should run the script. On a Windows platform you can associate php.exe with the double click option of the .php files, or you can make a batch file to run the script through PHP. The first line added to the script to work on Unix won't hurt on Windows, so you can write cross platform programs this way. A simple example of writing a command line PHP program can be found below.

Beispiel 23-1. Script intended to be run from command line (script.php) #!/usr/bin/php <?php if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) { ?> This is a command line PHP script with one option.   Usage:   <?php echo $argv[0]; ?> <option>   <option> can be some word you would like   to print out. With the --help, -help, -h,   or -? options, you can get this help. <?php } else {     echo $argv[1]; } ?>

In the script above, we used the special first line to indicate that this file should be run by PHP. We work with a CLI version here, so there will be no HTTP header printouts. There are two variables you can use while writing command line applications with PHP: $argc and $argv. The first is the number of arguments plus one (the name of the script running). The second is an array containing the arguments, starting with the script name as number zero ($argv[0]).

In the program above we checked if there are less or more than one arguments. Also if the argument was --help, -help, -h or -?, we printed out the help message, printing the script name dynamically. If we received some other argument we echoed that out.

If you would like to run the above script on Unix, you need to make it executable, and simply call it as script.php echothis or script.php -h. On Windows, you can make a batch file for this task:

Beispiel 23-2. Batch file to run a command line PHP script (script.bat) @c:\php\cli\php.exe script.php %1 %2 %3 %4

Assuming you named the above program script.php, and you have your CLI php.exe in c:\php\cli\php.exe this batch file will run it for you with your added options: script.bat echothis or script.bat -h.

See also the Readline extension documentation for more functions you can use to enhance your command line applications in PHP.