PHP flock(): Dateisperren für sicheres paralleles Schreiben

Wenn mehrere PHP-Skripte zur gleichen Zeit in dieselbe Datei schreiben, geraten Zähler, Logdateien und Cron-Jobs schnell durcheinander. Mit der Funktion flock() bringt PHP eine einfache Dateisperre mit, die genau das verhindert. Dieses Tutorial erklärt die vier Sperr-Modi und zeigt an konkreten Beispielen, wie sich parallele Schreibzugriffe sauber in den Griff bekommen lassen.

Warum braucht PHP flock Datei-Locks im Multi-Prozess-Betrieb?

PHP flock löst ein Problem mit Datei-Sperren, das vielen Anfängern erst bei hoher Last bewusst wird. Wer in PHP eine Datei beschreibt oder liest, setzt damit auf eine Ressource, die mehrere Skripte parallel ansprechen können. Genau hier liegt die Gefahr. Stellt sich ein Counter wie ein Klick-Zähler vor, den zwei Webseitenbesucher zur selben Millisekunde aufrufen, kann der Wert schief laufen, weil beide Skripte gleichzeitig lesen, addieren und zurückschreiben. PHP flock ist die eingebaute Antwort darauf: Eine Datei wird für die Dauer einer Operation gesperrt, sodass nur ein Schreiber zur Zeit aktiv ist.

Bevor Counter, Logfile-Append und Single-Instance-Cron als Patterns folgen, lohnt ein kurzer Blick auf die typischen Einsatzgebiete.

Datei-Sperren werden überall gebraucht, wo PHP Daten ohne Datenbank verwaltet. Logdateien, Counter, Konfigurations-Caches, Single-Instance-Cron-Skripte oder kleine Vereinsseiten sind klassische Anwendungsfälle. Dieses Tutorial zeigt die vier Modi der Funktion, drei praxisnahe Patterns und die wichtigsten Stolperfallen.

Syntax und die vier Modi von PHP flock()

Wer PHP flock einsetzt, sollte die Signatur kennen. Die Funktion erwartet einen offenen Datei-Zeiger und einen Operations-Modus, der den Zugriff durch parallele Prozesse steuert. Der Rückgabewert ist true bei Erfolg, false wenn der Lock nicht gesetzt werden konnte.

<?php

flock(resource $stream, int $operation, int &$would_block = null): bool

Es gibt bei PHP flock vier Modi, deren Namen nach POSIX-Tradition mit LOCK_ beginnen.

Wichtig zu wissen: flock() ist ein advisory Lock. Andere Prozesse, die ohne flock-Aufruf einfach in dieselbe Datei schreiben, werden nicht blockiert. Im PHP-Universum, in dem alle beteiligten Skripte sich an die Konvention halten, funktioniert das System aber zuverlässig. Der Lock wird beim fclose() oder am Skriptende automatisch freigegeben, auch wenn das Skript abstürzt.

Eine Counter-Datei mit PHP flock sicher inkrementieren

Das klassische Lehrbeispiel: Eine Datei hält einen Zähler. Bei jedem Aufruf soll der Wert um eins erhöht werden. Ohne Lock schießt der Zähler bei parallelen Aufrufen aus dem Tritt, weil zwei Skripte denselben Ausgangswert lesen.

<?php

$datei = 'counter.txt';

$fp = fopen($datei, 'c+');



if (flock($fp, LOCK_EX)) {

    $aktuell = (int) fread($fp, 1024);

    rewind($fp);

    ftruncate($fp, 0);

    fwrite($fp, (string) ($aktuell + 1));

    fflush($fp);

    flock($fp, LOCK_UN);

}

fclose($fp);

Der Modus 'c+' erstellt die Datei bei Bedarf und erlaubt Lesen und Schreiben am gleichen Pointer. Vor dem LOCK_EX ist die Datei für parallele Skripte gesperrt, danach lesen wir den aktuellen Wert, springen mit rewind() an den Anfang, kürzen die Datei und schreiben den neuen Wert. Erst nach dem flock(LOCK_UN) können andere Skripte zugreifen. Wer mit dem Lesen direkter Datei-Inhalte arbeitet, kann das Pattern auch mit file_get_contents in einem älteren Stil bauen, dort fehlt aber der eingebaute Lock-Schutz.

Logfile mit PHP flock im Append-Modus schreiben

Beim Arbeiten mit PHP flock im Logging-Kontext gilt eine einfache Regel: jeder Eintrag bekommt eine eigene Sperre. Logdateien sind der zweithäufigste Anwendungsfall für PHP flock. Im Append-Modus schreibt jeder Aufruf seine Zeile ans Ende, doch ohne Lock können sich zwei Einträge im selben Schreibblock vermischen und unleserlich werden.

<?php

function schreibeLog(string $eintrag): void

{

    $fp = fopen('app.log', 'a');

    if (flock($fp, LOCK_EX)) {

        fwrite($fp, date('c') . ' ' . $eintrag . PHP_EOL);

        flock($fp, LOCK_UN);

    }

    fclose($fp);

}



schreibeLog('Cron gestartet');

schreibeLog('Datensatz importiert');

Hier wird der Lock nur für die Dauer des einen fwrite()-Aufrufs gehalten. Das ist genau richtig: kurz, gezielt, höchstens ein paar Mikrosekunden. Wer eine umfangreiche Logger-Bibliothek braucht, sollte trotzdem zu Monolog oder einem ähnlichen Tool greifen, weil dort zusätzlich Log-Levels, Channels und Rotationen abgedeckt sind. Für das schnelle eigene Skript ist das Pattern oben aber völlig ausreichend und eine sinnvolle Ergänzung zum klassischen error_log(), das ohne explizite Locks auskommt.

Non-blocking Lock und Single-Instance-Cron mit PHP flock

PHP flock zeigt seine Stärke besonders im non-blocking Modus. Ein typisches Problem in der Produktion: Ein Cron-Job läuft alle fünf Minuten, braucht aber manchmal acht. Ohne Schutz starten zwei Instanzen parallel und treten sich gegenseitig auf die Füße. Mit LOCK_EX | LOCK_NB ist das Problem in vier Zeilen gelöst.

<?php

$lockfile = '/tmp/import.lock';

$fp = fopen($lockfile, 'c');



if (!flock($fp, LOCK_EX | LOCK_NB)) {

    echo 'Import laeuft bereits, Skript beendet.';

    exit;

}



/* Hier folgt die eigentliche Arbeit */

echo 'Import gestartet';

sleep(3);



flock($fp, LOCK_UN);

fclose($fp);

Das LOCK_NB-Flag sorgt dafür, dass flock() sofort false zurückgibt, falls ein anderer Prozess den Lock hält. Statt minutenlang zu warten, beendet sich das Skript einfach und überlässt die Arbeit dem schon laufenden Vorgang. Wenn der erste Prozess fertig ist (oder abstürzt), wird der Lock automatisch freigegeben und der nächste Cron-Lauf bekommt ihn.

Der folgende Ablauf zeigt, wie sich zwei Skripte beim Zugriff auf dieselbe gesperrte Datei verhalten, wenn eines den Lock hält.

flowchart TD
    A[Skript A oeffnet Datei] --> B[flock LOCK_EX]
    B --> C{Lock erhalten?}
    C -->|Ja| D[Datei bearbeiten]
    C -->|Nein| E[blockiert oder false bei LOCK_NB]
    D --> F[flock LOCK_UN]
    F --> G[fclose]
    G --> H[Skript B kann nun arbeiten]

Shared Lock mit PHP flock für reine Lesezugriffe

Nicht jeder Zugriff mit PHP flock auf eine Datei ist ein Schreibzugriff. Wer Konfigurationsdaten oder Cache-Inhalte liest, will mehrere parallele Leser zulassen, aber währenddessen keine Schreiber dazwischen haben. Das ist die Aufgabe von LOCK_SH.

<?php

$fp = fopen('config.json', 'r');



if (flock($fp, LOCK_SH)) {

    $inhalt = stream_get_contents($fp);

    flock($fp, LOCK_UN);

}

fclose($fp);



$daten = json_decode($inhalt ?? '[]', true);

Mehrere Skripte können parallel lesen, sobald aber jemand LOCK_EX anfordert, wartet er, bis alle Shared-Locks freigegeben sind. Im Gegenzug warten neue Shared-Locks, solange ein Exclusive-Lock aktiv ist. Diese Lese-Schreib-Geometrie ist genau das, was ein klassischer Datei-Cache braucht. In der Praxis sieht man dieses Pattern auch in Anwendungen, die ihre Daten als JSON-Datei halten und nur gelegentlich aktualisieren.

Stolperfallen bei PHP flock: advisory Lock und NFS

So nützlich PHP flock ist, es hat klare Grenzen. Erstens funktioniert die Sperre nur, wenn alle beteiligten Prozesse die Konvention einhalten. Ein Skript, das die Datei ohne flock() einfach beschreibt, wird nicht blockiert. In einer rein PHP-basierten Anwendung ist das selten ein Problem, sobald aber externe Tools, Skripte in anderen Sprachen oder manuelle Editor-Zugriffe ins Spiel kommen, kann advisory locking nicht mehr garantieren, dass es keine Konflikte gibt.

Zweitens ist das Verhalten über Netzwerk-Dateisysteme wie NFS plattformabhängig. Auf manchen Systemen funktioniert flock() nur lokal, auf anderen mit Einschränkungen. Wer Wert auf wirklich verlässliche Sperren legt und im Shared-Hosting auf NFS sitzt, sollte stattdessen eine Datenbank-Sperre nutzen, etwa SELECT ... FOR UPDATE in einer Transaktion. Die Tabelle tutorial_locks mit einem zentralen Datensatz für eine bestimmte Operation ist robuster als ein Datei-Lock auf NFS.

Drittens schluckt das Pattern oben gerne den Fehlerfall. Wer mit if (flock(...)) arbeitet und im else-Zweig nichts loggt, merkt nicht, wenn ein Lock dauerhaft scheitert. Eine kurze Notiz im Logfile per error_log() schafft hier Sicherheit. Und schließlich: Lock immer so kurz wie möglich halten, auf gar keinen Fall über externe API-Calls oder lange Berechnungen. Sonst werden alle anderen Prozesse blockiert.

Best Practices für PHP flock in der Produktion

Drei Regeln helfen, PHP flock sauber einzusetzen. Erstens immer den Rückgabewert prüfen und im Fehlerfall einen Log-Eintrag erzeugen. Zweitens den Lock nur über den eigentlichen Schreibvorgang halten, keine Sekunde länger. Drittens für Single-Instance-Skripte konsequent LOCK_NB nutzen, damit das Skript sich sauber beendet statt zu blockieren. In modernen Setups mit mehreren Webserver-Instanzen oder Container-Replicas verschiebt sich der saubere Weg ohnehin weg vom Datei-Lock hin zu Datenbank- oder Redis-basierten Locks. Für Einzel-Server-Setups bleibt flock() aber das einfachste Werkzeug.

Fazit zu PHP flock

PHP flock ist die eingebaute Antwort von PHP auf parallele Schreibzugriffe. Mit PHP flock lässt sich eine Datei mit LOCK_EX exklusiv sperren, mit LOCK_SH als Shared-Lock teilen und mit LOCK_UN oder automatisch beim fclose() wieder freigeben. Die wichtigsten Patterns rund um PHP flock sind sichere Counter, geschützte Logdateien und Single-Instance-Cron-Jobs mit LOCK_NB. Wer die Grenzen advisory Locks und das Verhalten über NFS kennt, baut mit PHP flock auch produktive PHP-Skripte robust gegen Race Conditions.