Features
PHP Manual

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 aktiviert. 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 heissen. 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 {PREFIX}/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 {PREFIX}/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.

Hinweis: Weil sowohl --enable-cli als auch --enable-cgi standardmäßig eingeschaltet sind, muss --enable-cli in Ihrem configure-Kommando nicht zwingend bedeuten, dass das CLI während make install nach {PREFIX}/bin/php kopiert wird.

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. Beginnend mit PHP 5 wird das CLI im Hauptordner als php.exe ausgeliefert. Die CGI-Version heisst php-cgi.exe.

Seit PHP 5 gibt es eine neue Datei, php-win.exe. Diese ist identisch mit der CLI-Version, die einzige Ausnahme besteht darin, dass php-win nichts ausgibt und somit keine Konsole bietet. (Es erscheint keine "MS-DOS-Eingabeaufforderung".) Dieses Verhalten ist ähnlich php-gtk. Sie sollten die folgende Option für ./configure benutzen: --enable-cli-win32.

Hinweis: Welche SAPI habe ich? Auf der Kommandozeile wird Ihnen die Eingabe von php -v verraten, ob Sie php als CGI oder CLI einsetzen. Sehen Sie sich auch die Funktion php_sapi_name() und die Konstante PHP_SAPI an.

Hinweis: Eine UNIX manual page wurde in PHP 4.3.2 hinzugefügt. Sie können sie ansehen, indem sie man php auf der Kommandozeile eintippen.

Beachtenswerte Unterschiede des CLI SAPI verglichen mit anderen SAPIs:

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] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

  -a               Run interactively
  -c <path>|<file> Look for php.ini file in this directory
  -n               No php.ini file will be used
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -f <file>        Parse <file>.
  -h               This help
  -i               PHP information
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -r <code>        Run PHP <code> without using script tags <?..?>
  -B <begin_code>  Run PHP <begin_code> before processing input lines
  -R <code>        Run PHP <code> for every input line
  -F <file>        Parse and execute <file> for every input line
  -E <end_code>    Run PHP <end_code> after processing all input lines
  -H               Hide any passed arguments from external tools.
  -s               Display colour syntax highlighted source.
  -v               Version number
  -w               Display source with stripped comments and whitespace.
  -z <file>        Load Zend extension <file>.

  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.

    Hinweis: 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 entgegen, 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ößenlimit 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.

# Dies führt nicht den angegebenen Code aus, sondern die Optionen von PHP anzeigen
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Dies übergibt das Argument '-h' an Ihr Skript und zeigt die Optionen von PHP nicht an
$ 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 Perl-Skript gestartet werden.

#!/usr/bin/php
<?php
var_dump
($argv);
?>
Angenommen, die Datei heißt 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.

Die Langformen der Optionen sind seit PHP 4.3.3 verfügbar.

Kommandozeilenoption
Option Langform Beschreibung
-a --interactive

Startet PHP im interaktiven Modus. Wenn Sie PHP mit der Readline-Erweiterung (die unter Windows nicht verfügbar ist) kompilieren, bekommen Sie eine feine Shell, komplett mit einer Auto-Vervollständigung (das bedeutet, Sie können anfangen, einen Variablennamen zu tippen, die TAB-Taste drücken und PHP vervollständigt den Namen) und einem Verlauf der letzten Zeilen, auf den mit den Pfeiltasten zugegriffen werden kann. Der Verlauf wird in der Datei ~/.php_history gespeichert.

Hinweis: Dateien, die mit auto_prepend_file und auto_append_file eingebunden wurden, werden in diesem Modus mit einigen Einschränkungen auch geparset - Funktionen müssen etwa vor dem Aufruf definiert werden.

-c --php-ini

Mit dieser Option kann man entweder ein Verzichnis angeben, wo nach php.ini gesucht werden soll, oder man kann eine eigene INI-Datei direkt angeben (diese muss nicht php.ini heissen). Zum Beispiel:

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php
Wenn Sie diese Option nicht angeben, wird die Datei an den vorgegebenen Orten gesucht.

-n --no-php-ini

php.ini komplett ignorieren. Diese Option gibt es seit PHP 4.3.0.

-d --define

Diese Option erlaubt es Ihnen, einen eigenen Wert für eine beliebige in php.ini erlaubte Direktive zu setzen. Die Syntax ist:

-d configuration_directive[=value]

Beispiele (die Zeilen sind aus layouttechnischen Gründen umgebrochen):

# Auslassen des Wertes setzt die Direktive auf "1"
$ php -d max_execution_time
      -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Übergeben eines leeren Wertes setzt die Direktive auf ""
php -d max_execution_time=
    -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# Die Direktive wird auf das gesetzt, was nach '=' kommt
$  php -d max_execution_time=20
       -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=doesntmakesense
       -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

-e --profile-info

Erweiterte Informationen für Debugger/Profiler erstellen.

-f --file

Parst und führt die angegebene Datei aus. Diese Option ist nicht verbindlich und kann weggelassen werden. Alleinige Angabe des Dateinamens ist ausreichend.

-h und -? --help und --usage Mit dieser Option bekommen Sie Informationen über die tatsächlichen Kommandozeilenoptionen und kurze Beschreibungen dazu.
-i --info Diese Kommandozeilenoption ruft phpinfo() auf und gibt das Ergebnis aus. Wenn PHP nicht korrekt funktioniert, ist es ratsam, php -i zu benutzen und nachzusehen, ob etwa Fehlermeldungen vor oder statt der Informationstabellen ausgegeben werden. Beachten Sie, dass die Ausgabe bei Verwendung des CGI-Modus in HTML erfolgt und deswegen ziemlich umfangreich ist.
-l --syntax-check

Diese Option stellt eine angenehme Methode bereit, nur eine Syntaxüberprüfung auf den angegebenen PHP-Code durchzuführen. Bei Erfolg wird der Text No syntax errors detected in <filename> auf die Standardausgabe geschrieben und der Rückgabewert ist 0. Bei Misserfolg wird der Text Errors parsing <filename> zusätzlich zur internen Parser-Fehlermeldung auf der Standardausgabe ausgegeben und der Rückgabewert auf 255 gesetzt.

Diese Option wird keine Fatalen Fehler (wie undefinierte Funktionen) finden. Benutzen Sie die Option -f, wenn sie auch diese überprüfen wollen.

Hinweis: Diese Option funktioniert nicht zusammen mit -r.

-m --modules

Wird diese Option benutzt, gibt PHP die eingebauten (und geladenen) PHP- und Zend-Module aus:

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-r --run

Diese Option erlaubt die Ausführung von PHP direkt aus der Kommandozeile. Die PHP-Start- und -End-Tags (<?php und ?>) werden nicht benötigt und verursachen Parserfehler, wenn sie dennoch vorhanden sind.

Hinweis: Man muss bei Benutzung dieser Form von PHP aufpassen, dass es zu keinen Kollisionen mit Kommandozeilenvariablen kommt.
Dieses Beispiel zeigt einen Parserfehler:

$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
Das Problem hier ist, dass die sh/bash Variablen auch ersetzt, wenn doppelte Anführungszeichen benutzt werden ("). Weil die Variable $foo wahrscheinlich nicht definiert ist, passiert nichts. Der tatsächliche Code, der an PHP übergeben wird, sieht so aus:
$ php -r " = get_defined_constants();"
Der korrekte Weg wäre, einfache Anführungszeichen zu benutzen ('). Variablen in einfachen Anführungszeichen werden von sh/bash nicht ersetzt.
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]
Wenn Sie eine andere Kommandozeilenumgebung als sh/bash benutzen, könnten Sie auf weitere Probleme stoßen. Sie können gerne einen Bugreport unter » http://bugs.php.net/ eintragen. Man kann dennoch leicht in Schwierigkeiten kommen, wenn man versucht, Kommandozeilenvariablen zu verwenden oder mit Backslashes zu escapen. Sie wurden gewarnt.

Hinweis: -r ist nur im CLI-SAPI verfügbar und nicht im CGI-SAPI

Hinweis: Diese Option ist für sehr rudimentäre Sachen gedacht. Deswegen werden manche Direktiven (etwa auto_prepend_file und auto_append_file) in diesem Modus ignoriert.

-B --process-begin

PHP-Code der ausgeführt werden soll, bevor stdin ausgewertet wird. Verfügbar seit PHP 5.

-R --process-code

PHP-Code der für jede Eingabezeile ausgeführt werden soll. Verfügbar seit PHP 5.

Es gibt zwei spezielle Variablen in diesem Modus: $argn und $argi. $argn enthält die Zeile, die PHP gerade verarbeitet und $argi enthält die Zeilennummer.

-F --process-file

PHP-Datei die für jede Eingabezeile ausgeführt werden soll. Verfügbar seit PHP 5.

-E --process-end

PHP-Code der nach der Verarbeitung der Eingabe ausgeführt werden soll. Verfügbar seit PHP 5.

Ein Beispiel, wie man die Optionen -B, -R und -E benutzt, um die Anzahl der Zeilen in einem Projekt zu zählen.

$ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
Total Lines: 37328

-s --syntax-highlight and --syntax-highlighting

Den Quelltext mit farbiger Syntaxhervorhebung anzeigen.

Diese Option benutzt den internen Mechanismus zum Analysieren der Datei, generiert eine HTML-Version mit Syntax-Highlighting davon, und schreibt sie auf die Standardausgabe. Beachten Sie, dass sie nur einen Block von <code> [...] </code>-HTML-Tags erzeugt, keine HTML-Header.

Hinweis: Diese Option funktioniert nicht zusammen mit -r.

-v --version

Schreibt die Version von PHP, PHP SAPI und Zend auf die Standardausgabe. Zum Beispiel:

$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

-w --strip

Den Quelltext mit entfernten Kommentaren und Leerzeichen anzeigen.

Hinweis: Diese Option funktioniert nicht zusammen mit -r.

-z --zend-extension

Eine Zend-Erweiterung laden. Wenn nur ein Dateiname angegeben wird, versucht PHP, die Erweiterung aus dem momentanen Standard-Bibliotheken-Pfad auf Ihrem System zu laden (auf Linux-Systemen normalerweise in /etc/ld.so.conf angegeben). Wenn ein Dateiname mit absoluter Pfadinformation übergeben wird, wird der Bibliotheken-Pfad des Systems nicht benutzt. Ein relativer Dateiname mit Pfadinformationen wird PHP nur veranlassen, zu versuchen, die Erweiterung in einem Pfad relativ zum aktuellen Verzeichnis zu laden.

Die ausführbare PHP-Version kann benutzt werden, um PHP-Skripte vollkommen unabhängig von einem Webserver auszuführen. Wenn Sie auf einem UNIX-System arbeiten, sollten Sie Ihrem Skript eine spezielle erste Zeile hinzufügen und es ausführbar machen, so dass das System erkennt, welches Programm das Skript ausführen soll. Auf einem Windows-System können Sie php.exe mit der Doppelklick-Option von .php-Dateien verknüpfen. Sie können auch eine Batchdatei erzeugen, um das Skript von PHP ausführen zu lassen. Die erste Zeile, die dem Skript hinzugefügt wird, damit es unter UNIX läuft, stört unter Windows nicht, so dass Sie auf diese Weise problemlos plattformübergreifende Programme schreiben können. Sie finden anschließend ein einfaches Beispiel, wie man ein Kommandozeilenprogramm in PHP schreibt.

Example#1 Ein Skript, das von der Kommandozeile aus ausgeführt werden soll (script.php)

#!/usr/bin/php
<?php

if ($argc != || in_array($argv[1], array('--help''-help''-h''-?'))) {
?>

Das ist ein Kommandozeilenprogramm in PHP mit einer Option.

  benutzung:
  <?php echo $argv[0]; ?> <option>

  <option> kann ein Wort sein, das Sie gerne
  ausgeben möchten. Mit den Optionen --help,
  -help, -h oder -? bekommen Sie diese Hilfe.

<?php
} else {
    echo 
$argv[1];
}
?>

In dem oben beschriebenen Skript haben wir die erste Zeile dazu benutzt anzugeben, dass die Datei von PHP ausgeführt werden soll. Wir arbeiten hier mit einer CLI-version, deswegen werden keine HTTP-Header ausgegeben. Es gibt zwei Variablen, die Sie in Kommandozeilen-Applikationen mit PHP benutzen können: $argc und $argv. Die erste ist die Anzahl der Argumente plus Eins (dem Namen des laufenden Skripts). Die zweite ist ein Array, das die Argumente enthält, beginnend mit dem Skriptnamen als Nummer Null ($argv[0]).

In dem oben genannten Programm haben wir überprüft, ob es weniger oder mehr als zwei Argumente gibt. Falls das Argument --help, -help, -h oder -? war, haben wir die Hilfe-Nachricht mit dem dynamisch übergebenen Skriptnamen ausgegeben. Wenn wir ein anderes Argument erhalten haben, haben wir es ausgegeben.

Wenn Sie das oben genannte Skript unter UNIX laufen lassen wollen, müssen Sie es zuerst ausführbar machen, und es danach einfach als script.php echothis oder script.php -h aufrufen. Unter Windows können Sie zu diesem Zweck eine Batchdatei erstellen:

Example#2 Batchdatei zur Ausführung eines Kommandozeilen-Skripts in PHP (script.bat)

@C:\php\php.exe script.php %1 %2 %3 %4

Angenommen, Sie haben das Programm script.php genannt und die CLI-php.exe hat den Pfad c:\php\php.exe, wird diese Batchdatei es mit den von Ihnen übergebnen Optionen ausführen: script.bat echothis oder script.bat -h.

Sehen Sie sich auch die zusätzlichen Funktionen in der Dokumentation der Readline-Extension an, um Ihre in PHP geschriebenen Kommandozeilenanwendungen zu verbessern.


Features
PHP Manual