finfo_file — Funktion · PHP-Referenz

Signatur

finfo_file(finfo $finfo, string $filename, int $flags = FILEINFO_NONE, ?resource $context = null): string|false

Beschreibung

finfo_file() ermittelt anhand der libmagic-Bibliothek Informationen über eine Datei. Die Funktion arbeitet dabei mit einer zuvor per finfo_open() erstellten finfo-Ressource (ab PHP 8.1 ein finfo-Objekt), die festlegt, welche Informationen abgefragt werden – typischerweise der MIME-Typ (FILEINFO_MIME_TYPE) oder die vollständige MIME-Zeichenkette inkl. Zeichenkodierung (FILEINFO_MIME).

Im Gegensatz zur rein namensbasierten Erkennung über die Dateiendung liest finfo_file() den tatsächlichen Inhalt der Datei, um deren Typ zuverlässig zu bestimmen. Dies ist besonders dann wichtig, wenn Nutzer Dateien hochladen, da der Dateiname manipuliert werden kann, der Dateiinhalt jedoch nicht so einfach.

Typische Einsatzgebiete sind die Validierung von Datei-Uploads (z. B. sicherstellen, dass eine hochgeladene Datei wirklich ein Bild ist), die dynamische Ausgabe von Dateien mit dem korrekten Content-Type-Header sowie die allgemeine Datei-Klassifizierung in Verarbeitungs-Pipelines.

Die Funktion ist der prozedurale Stil der objektorientierten Methode finfo::file(). Beide sind funktional identisch.

Parameter

Name	Typ	Default	Beschreibung
$finfo Pflicht	finfo		Eine `finfo`-Instanz (Objekt ab PHP 8.1 bzw. Ressource in älteren Versionen), die zuvor mit `finfo_open()` erstellt wurde und die gewünschten Flags enthält.
$filename Pflicht	string		Pfad zur zu analysierenden Datei. Kann ein lokaler Dateipfad oder ein per Stream-Wrapper erreichbarer Pfad sein.
$flags	int	FILEINFO_NONE	Optionale zusätzliche Flags, die das Verhalten der Analyse steuern. Können mit `\|` kombiniert werden. Überschreiben oder ergänzen die beim `finfo_open()`-Aufruf gesetzten Flags.
$context	resource\|null	null	Ein gültiger Stream-Kontext, der mit `stream_context_create()` erzeugt wurde. Wird für spezielle Stream-Optionen benötigt; in der Praxis meist `null`.

Rückgabewert

Typ

string|false

Beschreibung

Gibt einen String mit den ermittelten Dateiinformationen zurück (z. B. "image/jpeg" bei FILEINFO_MIME_TYPE). Schlägt die Analyse fehl (z. B. Datei nicht gefunden oder nicht lesbar), wird false zurückgegeben.

Beispiele

MIME-Typ einer hochgeladenen Datei ermitteln

<?php
// finfo-Instanz für MIME-Typ-Erkennung erstellen
$finfo = finfo_open(FILEINFO_MIME_TYPE);

$uploadedFile = '/tmp/uploaded_image.jpg';

$mimeType = finfo_file($finfo, $uploadedFile);

if ($mimeType !== false) {
    echo 'Erkannter MIME-Typ: ' . $mimeType . PHP_EOL;

    $erlaubt = ['image/jpeg', 'image/png', 'image/gif'];
    if (in_array($mimeType, $erlaubt, true)) {
        echo 'Datei ist ein gültiges Bild.' . PHP_EOL;
    } else {
        echo 'Unerlaubter Dateityp!' . PHP_EOL;
    }
} else {
    echo 'Datei konnte nicht analysiert werden.' . PHP_EOL;
}

finfo_close($finfo);

Erkannter MIME-Typ: image/jpeg Datei ist ein gültiges Bild.

MIME-Typ und Zeichenkodierung gemeinsam ausgeben

<?php
// FILEINFO_MIME liefert z. B. "text/plain; charset=utf-8"
$finfo = finfo_open(FILEINFO_MIME);

$datei = '/var/www/html/readme.txt';

$info = finfo_file($finfo, $datei);

if ($info !== false) {
    echo 'MIME-Info: ' . $info . PHP_EOL;

    // Content-Type-Header für direkte Dateiausgabe setzen
    header('Content-Type: ' . $info);
} else {
    http_response_code(500);
    echo 'Fehler beim Lesen der Dateiinformationen.';
}

finfo_close($finfo);

MIME-Info: text/plain; charset=utf-8

Objektorientierter Stil als Alternative

<?php
// Identisches Ergebnis mit der OOP-Schnittstelle
$finfo = new finfo(FILEINFO_MIME_TYPE);

$mimeType = $finfo->file('/tmp/dokument.pdf');

echo $mimeType; // Ausgabe: application/pdf

application/pdf

// Wichtig · Fallstricke

Sicherheitshinweis bei Datei-Uploads: Verlasse dich niemals allein auf den von Browsern gemeldeten MIME-Typ ($_FILES['datei']['type']), da dieser vom Angreifer frei manipuliert werden kann. Nutze stattdessen finfo_file(), um den tatsächlichen Inhalt zu prüfen.

Achtung: Auch finfo_file() bietet keinen absoluten Schutz – ein Angreifer kann eine Datei konstruieren, die z. B. als gültiges JPEG-Bild erkannt wird, aber schädlichen PHP-Code enthält. Stelle daher sicher, dass hochgeladene Dateien niemals direkt vom Webserver als PHP-Code ausgeführt werden können (z. B. durch Speicherung außerhalb des Document-Root oder Deaktivierung der PHP-Ausführung im Upload-Verzeichnis).

Unter Windows muss die php_fileinfo.dll-Extension in der php.ini aktiviert sein. Auf Unix-Systemen ist sie meist standardmäßig eingebunden.

Siehe auch

finfo_open finfo_close finfo_buffer finfo mime_content_type