escapeshellarg — Funktion · PHP-Referenz

Signatur

escapeshellarg(string $arg): string

Beschreibung

escapeshellarg() umschließt den übergebenen String mit einfachen Anführungszeichen und maskiert vorhandene einfache Anführungszeichen im String selbst. Das Ergebnis kann bedenkenlos als einzelnes Argument an Shell-Befehle übergeben werden, zum Beispiel in Kombination mit exec(), shell_exec(), system() oder passthru().

Auf Unix-Systemen werden einfache Anführungszeichen im Argument durch die Sequenz '\'' ersetzt, sodass der String als atomares Argument behandelt wird. Auf Windows-Systemen hingegen werden einfache Anführungszeichen entfernt und der String wird mit doppelten Anführungszeichen umschlossen; Sonderzeichen wie %, ! und ^ werden ebenfalls behandelt.

Die Funktion ist immer dann sinnvoll, wenn Benutzereingaben oder externe Daten als Argument an einen Shell-Befehl weitergegeben werden müssen. Sie verhindert Shell-Injection-Angriffe, bei denen ein Angreifer durch speziell konstruierte Eingaben eigene Befehle einschleusen könnte.

Zu beachten ist, dass escapeshellarg() nur für einzelne Argumente gedacht ist. Für die Maskierung ganzer Befehle steht escapeshellcmd() zur Verfügung – beide Funktionen haben jedoch unterschiedliche Zwecke und sollten nicht verwechselt werden.

Parameter

Name	Typ	Default	Beschreibung
$arg Pflicht	string		Der zu maskierende String, der als Shell-Argument verwendet werden soll, z. B. ein Dateiname oder eine Benutzereingabe.

Rückgabewert

Typ

string

Beschreibung

Gibt den maskierten String zurück, eingeschlossen in einfache (Unix) oder doppelte (Windows) Anführungszeichen, sodass er sicher als Shell-Argument verwendet werden kann.

Beispiele

Dateinamen sicher an einen Shell-Befehl übergeben

<?php
// Benutzereingabe – könnte gefährliche Zeichen enthalten
$filename = "mein dokument'; rm -rf /; echo '";

$escaped = escapeshellarg($filename);
echo $escaped . "\n";

// Sicherer Aufruf von 'wc -l' mit maskiertem Argument
$command = 'wc -l ' . $escaped;
$output = shell_exec($command);
echo $output;

'mein dokument'\''\''\'' rm -rf /; echo '\'''

Konvertierung einer Bilddatei mit ImageMagick

<?php
// Pfade könnten Leerzeichen oder Sonderzeichen enthalten
$inputFile  = '/var/uploads/mein bild (kopie).png';
$outputFile = '/var/output/ergebnis.jpg';

$command = sprintf(
    'convert %s %s',
    escapeshellarg($inputFile),
    escapeshellarg($outputFile)
);

exec($command, $output, $returnCode);

if ($returnCode === 0) {
    echo 'Konvertierung erfolgreich.';
} else {
    echo 'Fehler bei der Konvertierung.';
}

Konvertierung erfolgreich.

// Wichtig · Fallstricke

Sicherheitshinweis: Auch mit escapeshellarg() sollte der Aufruf externer Shell-Befehle auf ein Minimum beschränkt werden. Wenn möglich, sollten stattdessen native PHP-Funktionen oder Bibliotheken verwendet werden, um Shell-Aufrufe gänzlich zu vermeiden.

Windows-Verhalten: Auf Windows-Systemen entfernt die Funktion NULL-Bytes und bestimmte Sonderzeichen (%, !). Das Verhalten unterscheidet sich grundlegend von Unix, was bei plattformübergreifendem Code berücksichtigt werden muss.

Unterschied zu escapeshellcmd(): escapeshellcmd() maskiert einen ganzen Befehl, erlaubt aber mehrere Argumente. escapeshellarg() maskiert hingegen genau ein Argument und ist für Nutzereingaben in der Regel die sicherere Wahl.

Locale-Abhängigkeit: In älteren PHP-Versionen konnte das Ergebnis von der gesetzten Locale abhängen. Es empfiehlt sich, LC_ALL oder eine neutrale Locale zu verwenden, um unerwartetes Verhalten zu vermeiden.

Siehe auch

escapeshellcmd exec shell_exec system passthru proc_open