Signatur
Beschreibung
hash_update_file() ermöglicht es, den Inhalt einer Datei direkt in einen laufenden Hash-Berechnungsprozess einzuspeisen. Statt die Datei manuell zu öffnen und ihren Inhalt Stück für Stück mit hash_update() zu verarbeiten, übernimmt diese Funktion das Lesen vollständig intern – das spart Code und ist gedächtniseffizient, weil die Datei nicht komplett in den Speicher geladen werden muss.
Die Funktion arbeitet zusammen mit hash_init() (zum Erstellen des Kontexts) und hash_final() (zum Abschließen der Berechnung und Abrufen des Hash-Werts). Zwischen diesen Aufrufen kann hash_update_file() beliebig oft aufgerufen werden, um mehrere Dateien oder Dateien kombiniert mit Strings (hash_update()) zu hashen.
Über den optionalen dritten Parameter $context lässt sich ein Stream-Kontext übergeben, etwa um HTTP-Authentifizierung oder spezielle SSL-Einstellungen für entfernte Dateien zu konfigurieren – denn die Funktion unterstützt alle von PHP unterstützten Stream-Wrapper, also auch http://, ftp:// etc.
Typische Einsatzgebiete sind die Integritätsprüfung von Uploads, die Erzeugung von Checksums für Backup-Dateien oder das kombinierte Hashen mehrerer Dateien (z. B. um einen Fingerabdruck eines Verzeichnisinhalts zu erzeugen).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $context Pflicht | HashContext | Ein aktiver Hash-Kontext, der zuvor mit hash_init() erzeugt wurde. Der Kontext wird in-place aktualisiert. |
|
| $filename Pflicht | string | Pfad zur Datei, deren Inhalt in den Hash-Kontext eingespeist wird. Es werden alle von PHP unterstützten Stream-Wrapper akzeptiert (z. B. file://, http://, phar://). |
|
| $context | resource | null | Optionaler Stream-Kontext (erzeugt mit stream_context_create()), der für das Öffnen der Datei verwendet wird. Nützlich bei entfernten Ressourcen, die Authentifizierung oder besondere Transportoptionen erfordern. |
Rückgabewert
true bei Erfolg zurück. Gibt false zurück, wenn die Datei nicht geöffnet oder gelesen werden konnte (z. B. Datei nicht vorhanden, fehlende Leserechte).Beispiele
SHA-256-Prüfsumme einer Datei berechnen
<?php
$file = '/var/www/uploads/document.pdf';
$ctx = hash_init('sha256');
if (!hash_update_file($ctx, $file)) {
throw new RuntimeException('Datei konnte nicht gelesen werden: ' . $file);
}
$checksum = hash_final($ctx);
echo 'SHA-256: ' . $checksum . PHP_EOL;Mehrere Dateien und einen String kombiniert hashen
<?php
// Gemeinsamen Hash aus Konfigurationsdatei + Inhalt + Salt erzeugen
$ctx = hash_init('sha512');
// Salt voranstellen
hash_update($ctx, 'mein-geheimer-salt');
// Zwei Dateien einlesen
hash_update_file($ctx, '/etc/app/config.json');
hash_update_file($ctx, '/etc/app/routes.json');
// Ergebnis
$fingerprint = hash_final($ctx);
echo 'Fingerabdruck: ' . $fingerprint . PHP_EOL;Remote-Datei über HTTP hashen (mit Stream-Kontext)
<?php
$streamCtx = stream_context_create([
'http' => [
'timeout' => 10,
'user_agent' => 'PHP-Hash-Checker/1.0',
],
]);
$ctx = hash_init('md5');
if (hash_update_file($ctx, 'https://example.com/somefile.zip', $streamCtx)) {
echo 'MD5: ' . hash_final($ctx) . PHP_EOL;
} else {
echo 'Datei konnte nicht abgerufen werden.' . PHP_EOL;
}// Wichtig · Fallstricke
Sicherheitshinweis: Wird der Dateiname aus Benutzereingaben bezogen, muss er sorgfältig validiert werden, um Path-Traversal-Angriffe (../../etc/passwd) oder den Zugriff auf sensible Dateien zu verhindern. Verwende realpath() und prüfe, ob der aufgelöste Pfad innerhalb des erwarteten Verzeichnisses liegt.
Rückgabewert prüfen: Im Fehlerfall gibt die Funktion false zurück, erzeugt aber zusätzlich eine E_WARNING-Meldung. Der Hash-Kontext bleibt in diesem Fall unverändert. Fehlgeschlagene Aufrufe sollten immer explizit behandelt werden.
HMAC-Unterstützung: hash_update_file() funktioniert auch mit HMAC-Kontexten, die per hash_init('sha256', HASH_HMAC, $key) erstellt wurden – ideal für signierte Prüfsummen.
Große Dateien: Da die Datei intern in Blöcken gelesen wird, ist die Funktion auch für sehr große Dateien geeignet, ohne den PHP-Speicher zu überlasten.