getopt — Funktion · PHP-Referenz

Signatur

getopt(string $short_options, array $long_options = [], int &$rest_index = null): array|false

Beschreibung

getopt() analysiert die beim Aufruf eines PHP-CLI-Skripts übergebenen Kommandozeilenargumente und extrahiert daraus die definierten Kurz- und Langoptionen. Die Funktion ist ausschließlich im CLI-Kontext sinnvoll und liest standardmäßig aus der globalen $argv-Variable.

Kurzoptionen werden als String angegeben, wobei jeder Buchstabe eine Option darstellt. Ein einzelner Doppelpunkt (:) nach einem Buchstaben bedeutet, dass die Option einen Wert erwartet (Pflicht), zwei Doppelpunkte (::) bedeuten, dass der Wert optional ist. Langoptionen folgen demselben Prinzip, jedoch als Array mit Strings, z. B. ['verbose', 'output:'].

Der optionale dritte Parameter $rest_index wird mit dem Index des ersten nicht-geparsten Arguments in $argv befüllt. Dies ermöglicht die einfache Weiterverarbeitung verbleibender Argumente (z. B. Dateinamen) nach den Optionen.

Wird eine Option mehrfach angegeben, enthält der Rückgabewert statt eines Strings ein Array mit allen übergebenen Werten. Wenn eine Option ohne erwarteten Wert angegeben wird, ist ihr Wert im Ergebnis-Array false.

Parameter

Name	Typ	Default	Beschreibung
$short_options Pflicht	string		Zeichenkette mit den zu erkennenden Kurzoptionen. Jeder Buchstabe steht für eine Option. Ein nachfolgender `:` macht den Wert zur Pflicht, `::` macht ihn optional. Beispiel: `'hvo:f::'`.
$long_options	array	[]	Array mit Langoptionen (ohne führende `--`). Suffix `:` für Pflicht-Wert, `::` für optionalen Wert. Beispiel: `['help', 'output:', 'verbose::']`.
$rest_index	int	null	Wird nach dem Aufruf mit dem Index des ersten nicht-geparsten Elements in `$argv` befüllt. Ermöglicht den Zugriff auf Nicht-Options-Argumente wie Dateinamen.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein assoziatives Array zurück, dessen Schlüssel die erkannten Optionen (ohne Bindestriche) sind. Optionen ohne Wert erhalten den Wert false, Optionen mit Wert erhalten den jeweiligen String. Wird eine Option mehrfach übergeben, enthält der Eintrag ein Array aller Werte. Bei einem Fehler wird false zurückgegeben.

Beispiele

Kurzoptionen parsen (CLI-Skript)

<?php
// Aufruf: php script.php -v -o output.txt datei.csv

$opts = getopt('vo:', [], $restIndex);

if (isset($opts['v'])) {
    echo "Verbose-Modus aktiv" . PHP_EOL;
}

if (isset($opts['o'])) {
    echo "Ausgabedatei: " . $opts['o'] . PHP_EOL;
}

// Alle verbleibenden Argumente (nach den Optionen)
$remaining = array_slice($argv, $restIndex);
echo "Verbleibende Argumente: " . implode(', ', $remaining) . PHP_EOL;

Verbose-Modus aktiv Ausgabedatei: output.txt Verbleibende Argumente: datei.csv

Kurz- und Langoptionen kombiniert

<?php
// Aufruf: php script.php --verbose --output=report.html -n 5

$shortOpts = 'n:';
$longOpts  = ['verbose', 'output:', 'help'];

$opts = getopt($shortOpts, $longOpts);

if (array_key_exists('help', $opts)) {
    echo "Hilfe anzeigen..." . PHP_EOL;
    exit(0);
}

$verbose = array_key_exists('verbose', $opts);
$output  = $opts['output'] ?? 'stdout';
$count   = isset($opts['n']) ? (int)$opts['n'] : 1;

echo "Verbose: " . ($verbose ? 'ja' : 'nein') . PHP_EOL;
echo "Ausgabe: $output" . PHP_EOL;
echo "Anzahl: $count" . PHP_EOL;

Verbose: ja Ausgabe: report.html Anzahl: 5

Mehrfach verwendete Option ergibt Array

<?php
// Aufruf: php script.php -f eins.txt -f zwei.txt -f drei.txt

$opts = getopt('f:');

$files = (array)($opts['f'] ?? []);
foreach ($files as $file) {
    echo "Verarbeite: $file" . PHP_EOL;
}

Verarbeite: eins.txt Verarbeite: zwei.txt Verarbeite: drei.txt

// Wichtig · Fallstricke

Nur im CLI-Kontext: getopt() funktioniert ausschließlich, wenn das Skript über die Kommandozeile gestartet wird. In Web-Umgebungen ist $argv leer oder nicht gesetzt, was zu unbrauchbaren Ergebnissen führt.

Reihenfolge der Argumente: Die Funktion stoppt das Parsen, sobald sie auf ein Argument trifft, das keine Option ist und nicht als Wert einer Option erwartet wird (je nach Betriebssystem und libc-Implementierung kann das Verhalten variieren). Der Parameter $rest_index sollte daher genutzt werden, um den Übergang zu Nicht-Options-Argumenten zuverlässig zu erkennen.

Optionale Werte ohne Leerzeichen: Optionale Werte (::) müssen direkt an die Option angehängt werden (z. B. -fWert oder --option=Wert). Ein Leerzeichen zwischen Option und Wert wird nicht als Zuweisung interpretiert.

Validierung: getopt() validiert Eingaben nicht weiter. Empfangene Werte sollten vor Weiterverarbeitung auf Typ und Gültigkeit geprüft werden, um Fehleingaben oder unerwartetes Verhalten zu vermeiden.

Siehe auch

$argc $argv readline