file_get_contents in PHP verstehen

file_get_contents ist eine Funktion in PHP, mit der der Inhalt einer Datei in einen string eingelesen wird. Diese Funktion ist besonders nützlich bei der Arbeit mit Textdateien und kann verwendet werden, um den Inhalt einer Datei von einem Remote-Server oder einem lokalen Dateisystem abzurufen.

Syntax

Die Syntax der file_get_contents-Funktion lautet wie folgt:

PHP file_get_contents Funktionssyntax

file_get_contents(
    string $filename,
    bool $use_include_path = false,
    ?resource $context = null,
    int $offset = 0,
    ?int $maxlen = null
): string|false

• $filename: Der Pfad zur Datei oder die URL, die gelesen werden soll.
• $use_include_path: (optional) Wenn auf TRUE gesetzt, sucht die Funktion im Include-Pfad nach der Datei.
• $context: (optional) Eine gültige Kontextressource, die mit stream_context_create() erstellt wurde.
• $offset: (optional) Gibt an, wo das Lesen in der Datei beginnen soll. Ist $offset negativ, beginnt die Funktion am Ende der Datei.
• $maxlen: (optional) Gibt die maximale Anzahl der zu lesenden Bytes an.

Wie file_get_contents funktioniert

Die Funktion file_get_contents() nimmt einen Dateipfad oder eine URL als erstes Argument entgegen und gibt den gesamten Inhalt der Datei als einzelnen string zurück. Da alles auf einmal in den Speicher geladen wird, ist sie der einfachste Weg, eine ganze Datei zu lesen – aber auch das falsche Werkzeug für Dateien, die größer als der verfügbare Speicher sind.

Der Rückgabewert ist bei Erfolg der Dateiinhalt oder false bei einem Fehler. Da eine leere Datei legitimerweise einen leeren string "" zurückgibt (was falsy ist), sollte immer mit dem strikten Operator !== false verglichen werden, anstatt eine lockere Wahrheitsprüfung zu verwenden.

Eine lokale Datei lesen

Die häufigste Verwendung ist das Lesen einer kleinen lokalen Datei, beispielsweise einer Konfigurations- oder Vorlagendatei:

$content = file_get_contents('config.txt');

if ($content !== false) {
    echo $content;
} else {
    echo "Error: could not read the file.";
}

file_get_contents() gibt false bei einem Fehler zurück – beispielsweise wenn die Datei nicht existiert oder der Prozess keine Leseberechtigung hat – und gibt außerdem eine PHP-Warnung aus. Um die Warnung zu unterdrücken und den Fehler selbst zu behandeln, stellt man dem Aufruf den Fehlersteuerungsoperator @ voran:

$content = @file_get_contents('missing.txt');

if ($content === false) {
    echo "File is unavailable.";
}

Einen Teil einer Datei mit offset und maxlen lesen

Es muss nicht die gesamte Datei gelesen werden. Die Parameter $offset und $maxlen ermöglichen das Lesen eines Ausschnitts, was praktisch ist, um Header zu prüfen oder sehr große Dateien zu verarbeiten:

// File contains: "Hello, World!"
// Read 5 bytes starting at offset 7
echo file_get_contents('greeting.txt', false, null, 7, 5); // World

Ein häufiges Muster in der Praxis ist das Lesen von nur wenigen Bytes am Anfang, um den Dateityp zu erkennen, ohne die gesamte Datei in den Speicher zu laden.

Eine Remote-URL abrufen

Wenn die PHP-Einstellung allow_url_fopen aktiviert ist, kann eine http://- oder https://-URL übergeben werden, und file_get_contents() lädt den Antwort-Body herunter:

$html = file_get_contents('https://example.com');

if ($html !== false) {
    echo substr($html, 0, 100); // first 100 characters
}

Dies ist praktisch für schnelle Skripte, aber für HTTP-Aufrufe in der Produktion – bei denen Timeouts, benutzerdefinierte Header, POST-Bodys oder detaillierte Fehlercodes benötigt werden – ist die cURL-Erweiterung die robustere Wahl.

Eine JSON-API verwenden

Eine häufige Aufgabe ist das Abrufen von JSON von einer API und das Dekodieren in ein PHP-array. Kombiniere file_get_contents() mit json_decode():

$json = file_get_contents('https://api.example.com/data.json');
$data = json_decode($json, true); // true => associative array

echo $data['name'];

Header mit einem Stream-Kontext senden

Um benutzerdefinierte HTTP-Header zu senden, ein Timeout festzulegen oder eine POST-Anfrage zu senden, wird ein Stream-Kontext, der mit stream_context_create() erstellt wurde, als drittes Argument übergeben:

$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['key' => 'value']),
        'timeout' => 5,
    ],
]);

$response = file_get_contents('https://api.example.com/submit', false, $context);

Vorteile

• Einfach: liest eine gesamte Datei in einer einzigen Zeile aus, ohne dass ein Handle manuell geöffnet, gelesen und geschlossen werden muss.
• Schnell bei kleinen Dateien: effizient beim Lesen kleiner bis mittelgroßer Konfigurations-, Vorlagen- oder Datendateien.
• Vielseitig: funktioniert mit lokalen Pfaden und, mit allow_url_fopen, mit Remote-URLs für http/https/ftp über dieselbe API.

Einschränkungen und Fallstricke

• Speicherverbrauch: die gesamte Datei wird in den Speicher geladen; das Lesen einer mehrere Gigabyte großen Datei kann PHPs memory_limit überschreiten. Große Dateien sollten mit fopen() und fread() gestreamt oder mit fgets() zeilenweise gelesen werden.
• Keine HTTP-Fehlerdetails: bei einem Remote-404 oder 500 gibt der Aufruf false zurück (oder teilweisen Inhalt), ohne einen einfach zugänglichen Statuscode. Verwende die cURL-Erweiterung, wenn der Antwortstatus geprüft werden muss.
• allow_url_fopen muss aktiviert sein: Remote-URLs schlagen stillschweigend fehl, wenn diese php.ini-Direktive deaktiviert ist, was auf gehärteten Servern häufig der Fall ist.
• Leere Datei vs. Fehler: eine leere Datei gibt "" zurück, nicht false – ein weiterer Grund, mit !== false zu testen.

Verwandte Funktionen

• file_put_contents() — das Gegenstück zum Schreiben; speichert einen string in einem Aufruf in eine Datei.
• file() — liest eine Datei in ein array von Zeilen statt in einen einzelnen string.
• readfile() — liest eine Datei und schreibt sie direkt in den Ausgabepuffer (geeignet für das Bereitstellen von Downloads).
• fopen() — öffnet ein Handle für gestreimtes, inkrementelles Lesen und Schreiben.

Fazit

file_get_contents() ist eine einfache, vielseitige Funktion zum Einlesen des Inhalts lokaler Dateien und Remote-URLs in einen string. Ihre Bequemlichkeit macht sie zur ersten Wahl für kleine Dateien, Konfigurationsdaten und schnelle API-Aufrufe. Für sehr große Dateien ist Streaming mit fopen()/fread() vorzuziehen; für HTTP-Anfragen in der Produktion empfiehlt sich cURL. Mit einer strikten !== false-Prüfung des Rückgabewerts bleibt sie eine der praktischsten I/O-Funktionen in PHP.

Übungen