Wiederkehrende Aufgaben wie Backups, Newsletter-Versand oder Aufräumarbeiten laufen am besten automatisch im Hintergrund. Genau dafür gibt es Cronjobs, die ein PHP-Skript nach einem festen Zeitplan starten. Dieses Tutorial führt von der crontab-Syntax über den CLI-Aufruf bis zum sicheren Lock-File-Pattern, mit dem dein Job auch auf produktiven Servern zuverlässig läuft.
Was ist ein PHP Cronjob und wofür brauche ich ihn?
Ein PHP Cronjob ist ein PHP-Skript, das nach einem festen Zeitplan automatisch läuft. Statt morgens manuell ein Backup anzustoßen, einen Newsletter zu versenden oder veraltete Datensätze zu löschen, übernimmt der Cron-Daemon des Linux-Servers diese Aufgabe nach einer einmal hinterlegten Regel. Praktisch jeder professionelle PHP-Betrieb stützt sich auf solche Hintergrundjobs, weil sie die Anwendung schlanker und schneller halten.
Bevor crontab-Syntax und Lock-File-Pattern folgen, ein kurzer Überblick über die Themen, die dieses Tutorial in genau dieser Reihenfolge abarbeitet.
Dieses Tutorial erklärt die crontab-Syntax, zeigt den Aufruf von PHP per Kommandozeile, behandelt typische Stolperfallen rund um Pfade und Logging und führt zum sauberen Lock-File-Pattern mit flock(), das doppelte Ausführungen verhindert. Am Ende steht ein robustes Setup, das auf produktiven Servern stundenlang ohne Aufsicht läuft.
Die crontab-Syntax für den PHP Cronjob verstehen
Cron-Jobs werden in einer Datei gepflegt, die jeder User auf einem Linux-System über crontab -e öffnen kann. Jede Zeile besteht aus fünf Zeitfeldern und einem Befehl. Die Reihenfolge ist Minute, Stunde, Tag, Monat und Wochentag, gefolgt vom auszuführenden Kommando.
# Minute Stunde Tag Monat Wochentag Befehl
# 0 6 * * * taeglich um 6 Uhr
# */15 * * * * alle 15 Minuten
# 0 2 * * 0 jeden Sonntag um 2 Uhr
# 30 8 1 * * jeden Monatsersten um 08:30
0 6 * * * /usr/bin/php /var/www/cron/backup.php >> /var/log/backup.log 2>&1
Sterne bedeuten "jeder mögliche Wert", Schrägstriche wie */15 heißen "im Abstand von 15 Einheiten". Wer die Syntax noch nicht im Kopf hat, kann mit Tools wie crontab.guru seine Ausdrücke vorab testen, bevor sie in die crontab landen. Praktisch hilft auch der Kommentar mit # direkt vor der Zeile, der den Job später selbsterklärend macht.
PHP Cronjob als CLI-Skript ausführen
Ein PHP Cronjob läuft nicht über den Webserver, sondern direkt über das CLI-Binary von PHP. Der Pfad zur PHP-CLI lässt sich auf jedem System mit which php ermitteln und liegt typischerweise unter /usr/bin/php oder /usr/local/bin/php. Wichtig zu wissen: PHP-CLI nutzt eine eigene php.ini, oft /etc/php/8.4/cli/php.ini, mit anderen Limits als die Web-Variante. Das memory_limit ist meist höher, max_execution_time häufig auf 0 gesetzt, was bedeutet "kein Timeout".
# PHP-Pfad ermitteln
which php
# Ergebnis z.B. /usr/bin/php
# Skript manuell aufrufen, bevor es in die crontab geht
/usr/bin/php /var/www/cron/backup.php
# Logging-Variante zum Debuggen
/usr/bin/php /var/www/cron/backup.php >> /tmp/test.log 2>&1
cat /tmp/test.log
Der Test von Hand ist Pflicht. Erst wenn das Skript an der Kommandozeile ohne Fehler durchläuft, lohnt sich der Eintrag in die crontab. Sonst landet die Fehlersuche im Cron-Log, was deutlich umständlicher ist als ein direkter Aufruf mit sichtbarer Ausgabe. Mehr Details zur PHP-CLI gibt es im Tutorial zur PHP-Kommandozeile.
Working-Directory und absolute Pfade im PHP Cronjob
Ein klassischer Stolperstein ist das Working-Directory. Beim Browser-Aufruf liegt es im Document-Root, beim Cron-Aufruf meist im Home-Verzeichnis des Users. Wer mit relativen Pfaden arbeitet, etwa require 'config.php', scheitert mit "File not found" oder "Class not found", obwohl alles korrekt aussieht.
<?php
/* Working-Directory am Skript-Anfang festlegen */
chdir(__DIR__);
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/config.php';
echo '[' . date('Y-m-d H:i:s') . '] Backup gestartet' . PHP_EOL;
/* eigentliche Backup-Logik */
$db = new PDO($dsn, $user, $passwort);
$db->exec('OPTIMIZE TABLE benutzer');
echo '[' . date('Y-m-d H:i:s') . '] Backup beendet' . PHP_EOL;
Zwei Regeln helfen: erstens immer chdir(__DIR__) am Anfang setzen, zweitens alle Pfade absolut formulieren. Damit funktioniert das Skript unabhängig davon, ob es per Cron, manuell oder vom Deploy-Tool gestartet wird. Wer Composer einsetzt, sollte dessen Autoloader explizit über den vollen Pfad inkludieren.
Logging für den PHP Cronjob mit stdout und stderr
Standardmäßig schickt Cron jede Ausgabe eines PHP Cronjob als E-Mail an den Account-User. Auf den meisten Servern ist diese Mail-Zustellung gar nicht eingerichtet, sodass die Ausgabe ins Leere geht. Sinnvoller ist eine Umleitung in eine Logdatei, die später mit tail -f oder einem Log-Rotator beobachtet werden kann.
0 6 * * * /usr/bin/php /var/www/cron/backup.php >> /var/log/backup.log 2>&1
# >> haengt an die Datei an, statt zu ueberschreiben
# 2>&1 leitet stderr (Kanal 2) auf stdout (Kanal 1) um
# Damit landen Fehler und normale Ausgaben in derselben Datei
Im PHP-Skript selbst lohnt es sich, jede Aktion mit Zeitstempel zu loggen. Das [Y-m-d H:i:s]-Präfix vor jeder Zeile macht später die Korrelation mit anderen Logs einfach. Wer es noch sauberer haben möchte, schreibt strukturierte Logs über error_log() oder einen externen Logger, der die Ausgabe in einem definierten Format wie JSON ablegt.
Lock-Files mit flock gegen Doppellauf
Ein PHP Cronjob, der länger braucht als sein Ausführungsintervall, kann mit der nächsten Instanz kollidieren. Bei einem Backup-Job würden so zwei Prozesse gleichzeitig auf der gleichen Datenbank schreiben, ein Newsletter könnte doppelt versendet werden. Das Lock-File-Pattern mit flock() schützt davor.
<?php
$lockDatei = sys_get_temp_dir() . '/backup.lock';
$lockHandle = fopen($lockDatei, 'c');
if ($lockHandle === false) {
exit('Lock-Datei nicht erreichbar.' . PHP_EOL);
}
/* LOCK_EX = exklusive Sperre, LOCK_NB = nicht blockieren */
if (!flock($lockHandle, LOCK_EX | LOCK_NB)) {
exit('Backup laeuft bereits, breche ab.' . PHP_EOL);
}
try {
echo 'Backup laeuft...' . PHP_EOL;
sleep(30);
echo 'Backup fertig.' . PHP_EOL;
} finally {
flock($lockHandle, LOCK_UN);
fclose($lockHandle);
}
Die Kombination LOCK_EX | LOCK_NB ist entscheidend. Ohne LOCK_NB würde das Skript warten, bis die Sperre frei wird, was den nächsten Job einfach hinten anstellt. Mit LOCK_NB fällt es sofort durch, sobald der Vorgänger noch läuft. Genau dieses Verhalten ist beim Cron meistens erwünscht, weil ein verzögerter Backup-Lauf in der Regel keinen Sinn ergibt.
flowchart TD
A[Cron-Daemon prueft Zeitplan] --> B{Zeit erreicht?}
B -->|Ja| C[Befehl mit php-cli starten]
C --> D[chdir + require autoload]
D --> E[Lock-Datei mit flock]
E --> F{Lock erhalten?}
F -->|Nein| G[Sofort beenden]
F -->|Ja| H[Eigentliche Logik ausfuehren]
H --> I[Log in Datei schreiben]
I --> J[Heartbeat senden]
J --> K[Lock loesen, fertig]
Shared Hosting und Web-UI für den PHP Cronjob
Auf vielen Shared-Hosting-Paketen gibt es keine direkte Shell, dafür eine Weboberfläche für den PHP Cronjob. Plesk, cPanel, ISPConfig oder die Synology DiskStation bieten allesamt eine UI, in der die Felder und der Befehl per Formular eingetragen werden. Das Prinzip ist identisch zur klassischen crontab, nur die Eingabe ist freundlicher.
Zu beachten ist, dass die Mindest-Frequenz auf manchen Hostern bei 5 oder 10 Minuten liegt und kürzere Intervalle stillschweigend ignoriert werden. Auch ist die PHP-Version manchmal älter als beim Webaufruf, weil eine separate CLI-Version installiert ist. Vor dem Eintrag empfiehlt sich ein Blick in die Hosting-Doku oder ein Test mit <?php echo PHP_VERSION; als minimal-Skript, um die richtige PHP-Version zu identifizieren.
Wer Shell-Zugang hat, findet die crontab-Dateien systemseitig meist unter /var/spool/cron/crontabs/<user>. Daneben gibt es die system-weite /etc/crontab und das Verzeichnis /etc/cron.d/, in dem Pakete eigene Job-Dateien ablegen. Wer einen verschollenen Job sucht, findet ihn in der Regel an einem dieser drei Orte.
WordPress, wp-cron.php und echte Cronjobs
Eine eigene Erwähnung verdient wp-cron.php, weil viele PHP-Cronjob-Suchen aus dem WordPress-Umfeld kommen. WordPress nutzt eine Pseudo-Cron-Mechanik: Bei jedem Seitenaufruf prüft wp-cron.php, ob geplante Aufgaben fällig sind, und führt sie im Request-Kontext aus. Auf Seiten mit wenig Traffic werden Aufgaben dadurch verzögert, auf Seiten mit viel Traffic kostet das jeden Besucher Performance.
Die robuste Lösung besteht aus zwei Schritten. Erstens den internen Auto-Trigger in der wp-config.php deaktivieren, zweitens einen echten Cronjob auf den Endpunkt setzen.
<?php
/* in wp-config.php hinzufuegen */
define('DISABLE_WP_CRON', true);
# crontab-Eintrag, der wp-cron.php alle 5 Minuten aufruft
*/5 * * * * /usr/bin/php /var/www/wordpress/wp-cron.php >/dev/null 2>&1
Damit läuft die WordPress-Cron-Mechanik unabhängig von Besuchen und in einem vorhersehbaren Takt. Das Prinzip lässt sich auf jedes andere CMS übertragen, das auf request-getriggertes Scheduling setzt.
Monitoring und Heartbeat für den PHP Cronjob
Stille Ausfälle sind die schlimmste Sorte. Ein PHP Cronjob, der fünf Tage lang nicht läuft, weil ein Server-Update einen Pfad verschoben hat, kann massive Datenverluste verursachen. Ein Heartbeat-Service wie healthchecks.io löst das, indem das Skript am Ende einen kurzen Ping an eine eindeutige URL schickt.
<?php
/* Heartbeat zum externen Monitoring */
$heartbeat = 'https://hc-ping.com/MEINE-CHECK-ID';
@file_get_contents($heartbeat);
echo '[' . date('Y-m-d H:i:s') . '] Job erfolgreich beendet' . PHP_EOL;
Bleibt der Ping aus, bekommt der Admin nach einer konfigurierbaren Karenzzeit eine E-Mail oder Slack-Nachricht. Wer keinen externen Service möchte, kann das Gleiche selbst bauen, etwa indem das Skript einen Timestamp in eine Datei schreibt und ein zweites Monitoring-Skript regelmäßig prüft, ob die Datei jünger als das erwartete Intervall ist.
Fazit zum PHP Cronjob
Ein produktiver PHP Cronjob braucht mehr als eine crontab-Zeile. Mit dem richtigen Setup aus CLI-Aufruf, absolutem Working-Directory, Logging via stderr-Umleitung, Lock-File via flock() und einem Heartbeat zum Monitoring wird aus einem fragilen Bastel-Skript ein verlässlicher Hintergrundjob. Die crontab-Syntax mit fünf Feldern ist schnell gelernt, die typischen Stolperfallen wie falsches Working-Directory oder verschluckte E-Mail-Logs sind mit den vorgestellten Patterns zuverlässig im Griff. Damit laufen Backups, Newsletter und Cleanup-Jobs zuverlässig im Hintergrund, ohne dass die eigentliche Webanwendung etwas davon mitbekommt.
