proc_open
(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)
proc_open — Führt ein Kommando aus und öffnet Dateizeiger für die Ein- und Ausgabe
Beschreibung
array|string
$command,array
$descriptor_spec,array
&$pipes,?string
$cwd = null,?array
$env_vars = null,?array
$options = null): resource|false
proc_open() ist äquivalent zu popen(), ermöglicht aber einen höheren Grad von Kontrolle über die Programmausführung.
Parameter-Liste
-
command -
Das auszuführende Kommandozeile als String. Sonderzeichen müssen ordnungsgemäß maskiert und Argumente ggf. in Anführungszeichen eingeschlossen werden.
Hinweis: Unter Windows wird, falls
bypass_shellinoptionsnicht auftruegesetzt ist, dascommandmit dem Flag/cals nicht in Anführungszeichen eingeschlossene Zeichenkette (d. h. genau wie an proc_open() übergeben) an cmd.exe übergeben (genauer gesagt an%ComSpec%). Dies kann dazu führen, dass cmd.exe die umschließenden Anführungszeichen voncommandentfernt (Details sind der Dokumentation von cmd.exe zu entnehmen), was zu unerwartetem und potentiell sogar gefährlichem Verhalten führen kann, da Fehlermeldungen von cmd.exe das übergebenecommandoder Teile davon enthalten können (siehe Beispiel weiter unten).Von PHP 7.4.0 an kann
commandals Array von Befehlsparametern übergeben werden. In diesem Fall wird der Prozess direkt gestartet (ohne Umweg über die Shell) und PHP kümmert sich um das nötige Maskieren der Argumente.Hinweis:
Unter Windows erfolgt die Argumentenmaskierung der Array-Elemente unter der Annahme, dass das Parsen der Kommandozeile des auszuführenden Kommandos kompatibel ist mit dem Parsen der Kommandozeile durch die VC-Laufzeitumgebung.
-
descriptor_spec -
Ein indexiertes Array, in dem die Schlüssel die Descriptornummer repräsentieren und die Werte die Art und Weise, in der PHP die Descriptoren an die Child-Prozesse übergibt. 0 steht dabei für stdin, 1 für stdout und 2 für stderr.
Jedes Element kann sein:
-
Ein Array, das die Pipe beschreibt, die an den Prozess übergeben
wird. Das erste Element ist der Descriptortyp, das zweite Element ist
eine Option für den angegebenen Typ. Gültige Typen sind
pipe(das zweite Element ist entwederr, um das Ende des Leseprozesses der Pipe an den Prozess zu übergeben, oderw, um das Ende des Schreibprozesses zu übergeben) undfile(das zweite Element ist ein Dateiname). Es ist zu beachten, dass alles außer w wie r behandelt wird. -
Eine Streamressource, die einen echten Filedescriptor repräsentiert
(z. B. geöffnete Dateien, Sockets,
STDIN).
Die Filedescriptor-Nummern sind nicht limitiert auf 0, 1 und 2 - Sie können jede gültige Filedescriptor-Nummer angeben, die an den Kindprozess übergeben wird. Dies erlaubt es Ihrem Skript, mit anderen Skripten zu interagieren, die als "Co-Prozesse" laufen. Dies ist insbesondere dann nützlich, wenn Passwörter auf sichere Weise an Programme wie PGP, GPG und openssl übergeben werden sollen. Es ist ebenfalls nützlich, um Lesestatus-Informationen zu erhalten, die von diesen Programmen für zusätzliche Filedescriptoren ermittelt werden.
-
Ein Array, das die Pipe beschreibt, die an den Prozess übergeben
wird. Das erste Element ist der Descriptortyp, das zweite Element ist
eine Option für den angegebenen Typ. Gültige Typen sind
-
pipes -
Enthält ein numerisches Array von Dateizeigern, die der PHP-Seite jeder erstellten Pipe entsprechen.
-
cwd -
Das initiale Arbeitsverzeichnis des Kommandos. Dies muss ein absoluter Pfadname sein. Wenn Sie den Standardwert verwenden möchten (dies wäre das Arbeitsverzeichnis des aktuellen PHP-Prozesses), muss der Wert
nullsein. -
env_vars -
Ein Array mit den Umgebungsvariablen für das auszuführende Kommando, oder
null, wenn Sie die gleiche Umgebung wie der aktuelle PHP-Prozess nutzen wollen. -
options -
Erlaubt Ihnen, zusätzliche Optionen anzugeben. Derzeit unterstützte Optionen sind:
-
suppress_errors(nur unter Windows): Unterdrückt Fehlermeldungen, die durch diese Funktion hervorgerufen werden, sofern der Wert auftruegesetzt wurde. -
bypass_shell(nur unter Windows): umgeht diecmd.exe-Shell, wenn der Wert auftruegesetzt wurde. -
blocking_pipes(nur unter Windows): erzwingt blockierende Pipes, wenn der Wert auftruegesetzt wurde. -
create_process_group(nur unter Windows): ermöglicht dem KindprozessCTRLEreignisse zu behandeln, wenn der Wert auftruegesetzt wurde. -
create_new_console(nur unter Windows): der neue Prozess hat eine neue Konsole anstatt die Konsole des Elternprozesses zu erben
-
Rückgabewerte
Gibt eine Ressource zurück, die den Prozess repräsentiert, der unter
Verwendung von proc_close() freigegeben werden soll, wenn
Sie ihn beenden. Im Fehlerfall wird false zurückgegeben.
Changelog
| Version | Beschreibung |
|---|---|
| 7.4.4 |
Die Option create_new_console wurde dem Parameter
options hinzugefügt.
|
| 7.4.0 |
proc_open() akzeptiert nun ebenfalls ein Array
für das command.
|
| 7.4.0 |
Die Option create_process_group wurde dem Parameter
options hinzugefügt.
|
Beispiele
Beispiel #1 Ein proc_open()-Beispiel
<?php
$descriptorspec = array(
0 => array("pipe", "r"), // stdin ist eine Pipe, von der das Child liest
1 => array("pipe", "w"), // stdout ist eine Pipe, in die das Child schreibt
2 => array("file", "/tmp/error-output.txt", "a") // stderr ist eine Datei,
// in die geschrieben wird
);
$cwd = '/tmp';
$env = array('some_option' => 'aeiou');
$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);
if (is_resource($process)) {
// $pipes sieht nun so aus:
// 0 => Schreibhandle, das auf das Child stdin verbunden ist
// 1 => Lesehandle, das auf das Child stdout verbunden ist
// Jedwede Fehlerausgabe wird an /tmp/error-output.txt angefügt
fwrite($pipes[0], '<?php print_r($_ENV); ?>');
fclose($pipes[0]);
echo stream_get_contents($pipes[1]);
fclose($pipes[1]);
// Es ist wichtig, dass Sie alle Pipes schließen, bevor Sie
// proc_close aufrufen, um Deadlocks zu vermeiden
$return_value = proc_close($process);
echo "Rückgabewert des Kommandos: $return_value\n";
}
?>
Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:
Array
(
[some_option] => aeiou
[PWD] => /tmp
[SHLVL] => 1
[_] => /usr/local/bin/php
)
Rückgabewert des Kommandos: 0
Beispiel #2 proc_open()-Eigenheit unter Windows
Während man erwarten könnte, dass das folgende Program die Datei
filename.txt nach dem Text suche
durchsucht und die Ergebnisse ausgibt, verhält es sich ganz anders.
<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "suche" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>
Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
Der Befehl "findstr" "suche" "filename.txt" ist entweder falsch geschrieben oder konnte nicht gefunden werden.
Um dieses Verhalten zu vermeiden, ist es üblicherweise ausreichend das
command in zusätzliche Anführungszeichen einzuschließen:
$cmd = '""findstr" "suche" "filename.txt""';
Anmerkungen
Hinweis:
Windows-Kompatibilität: Descriptoren höher 2 (stderr) sind Childprozessen als vererbbare Handles verfügbar, aber da die Windows-Architektur die Nummern der Filedescriptoren nicht mit Low-Level-Handles verbindet, hat der Kindprozess (bis jetzt) keine Möglichkeit, diese Handles anzusprechen. Stdin, stdout und stderr funktionieren wie erwartet.
Hinweis:
Wenn Sie nur eine unidirektionale (Einweg-) Prozesspipe benötigen, nutzen Sie besser popen(), da diese Funktion leichter zu verwenden ist.
Siehe auch
- popen() - Öffnet einen Dateizeiger für einen Prozess
- exec() - Führt ein externes Programm aus
- system() - Führt ein externes Programm aus und zeigt dessen Ausgabe an
- passthru() - Führt ein externes Programm aus und zeigt dessen Ausgabe an
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by seconds and microseconds
- Der Backtick-Operator
