Signatur
Beschreibung
hash_file() liest den Inhalt einer Datei und berechnet darüber einen Hash-Wert mit dem gewählten Algorithmus (z. B. sha256, md5, sha512). Die Funktion ist besonders nützlich zur Integritätsprüfung von Dateien, etwa um Downloads zu verifizieren oder sicherzustellen, dass eine Datei nicht manipuliert wurde.
Im Gegensatz zu hash(), das einen String als Eingabe erwartet, liest hash_file() die Datei intern in Blöcken ein, sodass auch sehr große Dateien effizient verarbeitet werden können, ohne den gesamten Inhalt in den Arbeitsspeicher laden zu müssen.
Der Parameter $algo akzeptiert alle Algorithmen, die von hash_algos() zurückgegeben werden. Typische Anwendungsfälle sind das Prüfen von Prüfsummen (Checksums) beim Herunterladen von Software sowie das Erkennen von Dateiänderungen in Backup- oder Synchronisationssystemen.
Über den optionalen Parameter $options können bei manchen Algorithmen (z. B. xxh3) zusätzliche Optionen wie ein seed-Wert übergeben werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $algo Pflicht | string | Name des Hash-Algorithmus, z. B. sha256, md5 oder sha512. Eine vollständige Liste liefert hash_algos(). |
|
| $filename Pflicht | string | Pfad zur Datei, deren Inhalt gehasht werden soll. Unterstützt auch Stream-Wrapper wie http:// oder ftp://, sofern diese aktiviert sind. |
|
| $binary | bool | false | Wenn true, wird der Hash als rohe Binärdaten zurückgegeben. Wenn false (Standard), wird eine hexadezimale Zeichenkette zurückgegeben. |
| $options | array | [] | Optionale algorithmusspezifische Parameter, z. B. ein seed-Wert für nicht-kryptografische Algorithmen wie xxh3. Seit PHP 8.1.0 verfügbar. |
Rückgabewert
$binary = true) zurück. Im Fehlerfall (z. B. Datei nicht gefunden oder kein Lesezugriff) wird false zurückgegeben.Beispiele
SHA-256-Prüfsumme einer lokalen Datei berechnen
<?php
$file = '/var/www/html/downloads/setup.zip';
$hash = hash_file('sha256', $file);
if ($hash === false) {
echo 'Fehler: Datei konnte nicht gelesen werden.';
} else {
echo 'SHA-256: ' . $hash . PHP_EOL;
}
// Beispielausgabe:
// SHA-256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855Integrität einer heruntergeladenen Datei überprüfen
<?php
// Erwartete Prüfsumme, z. B. aus der offiziellen Download-Seite
$expectedHash = 'b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576ec3e73c5c238e4ed';
$downloadedFile = '/tmp/archive.tar.gz';
$actualHash = hash_file('sha256', $downloadedFile);
if (hash_equals($expectedHash, $actualHash)) {
echo 'Datei ist integer — Hash stimmt überein.' . PHP_EOL;
} else {
echo 'WARNUNG: Hash stimmt NICHT überein! Datei möglicherweise beschädigt oder manipuliert.' . PHP_EOL;
}Datei-Hash als Binärdaten für weiteres Hashing verwenden
<?php
// Binären Hash einer Datei erzeugen und ihn als Base64 ausgeben
$file = '/var/www/upload/bild.jpg';
$binaryHash = hash_file('sha256', $file, true);
if ($binaryHash !== false) {
$base64Hash = base64_encode($binaryHash);
echo 'Base64-Hash: ' . $base64Hash . PHP_EOL;
}// Wichtig · Fallstricke
Sicherheitshinweis: Für kryptografisch sichere Integritätsprüfungen sollten nur starke Algorithmen wie sha256 oder sha512 eingesetzt werden. MD5 und SHA-1 gelten als kryptografisch gebrochen und sollten für sicherheitsrelevante Zwecke nicht mehr verwendet werden.
Vergleich von Hashes: Beim Vergleich zweier Hash-Werte sollte stets hash_equals() statt dem ===-Operator verwendet werden, um Timing-Angriffe zu verhindern.
Stream-Wrapper: Die Funktion unterstützt zwar Remote-Streams (z. B. http://), jedoch sollte aus Sicherheitsgründen keine Benutzereingabe ungeprüft als Dateiname übergeben werden (Path-Traversal-Risiko).
Seit PHP 8.1.0 steht der vierte Parameter $options zur Verfügung; ältere PHP-Versionen akzeptieren ihn nicht.