Signatur
Beschreibung
GearmanClient ist die zentrale Klasse der PHP-Gearman-Erweiterung und ermöglicht es, Aufgaben (Jobs) an einen oder mehrere Gearman-Job-Server zu senden, die diese dann an registrierte Worker verteilen. Der Client kann Jobs synchron (blockierend) oder asynchron (im Hintergrund) ausführen lassen.
Ein typischer Anwendungsfall ist die Auslagerung rechenintensiver oder zeitkritischer Aufgaben – etwa Bildverarbeitung, E-Mail-Versand oder Datenbankoperationen – in separate Worker-Prozesse. Der Client definiert dabei lediglich den Funktionsnamen und die zu übergebenden Daten, während Worker-Prozesse die eigentliche Verarbeitungslogik bereitstellen.
Die Klasse unterstützt mehrere Job-Ausführungsmodi: synchron (doNormal), im Hintergrund (doBackground), mit hoher Priorität (doHigh), sowie die Ausführung mehrerer Tasks parallel über addTask und runTasks. Callbacks erlauben es, auf Ereignisse wie abgeschlossene Tasks, Fehler oder Status-Updates zu reagieren.
Voraussetzung für den Einsatz ist die installierte PHP-Erweiterung gearman sowie ein laufender Gearman-Job-Server (standardmäßig auf Port 4730). Mehrere Job-Server können per addServer hinzugefügt werden, um Lastverteilung und Ausfallsicherheit zu erreichen.
Beispiele
Einfacher synchroner Job mit GearmanClient
<?php
// Job-Server hinzufügen und einen synchronen Job ausführen
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);
// Sendet einen Job an die Funktion 'reverse' mit dem Argument 'Hallo Welt'
$result = $client->doNormal('reverse', 'Hallo Welt');
if ($client->returnCode() == GEARMAN_SUCCESS) {
echo 'Ergebnis: ' . $result . PHP_EOL;
} else {
echo 'Fehler: ' . $client->error() . PHP_EOL;
}Mehrere Tasks parallel mit Callbacks ausführen
<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);
// Callback für abgeschlossene Tasks registrieren
$client->setCompleteCallback(function (GearmanTask $task) {
echo 'Task abgeschlossen. Ergebnis: ' . $task->data() . PHP_EOL;
});
// Callback für fehlgeschlagene Tasks
$client->setFailCallback(function (GearmanTask $task) {
echo 'Task fehlgeschlagen: ' . $task->functionName() . PHP_EOL;
});
// Mehrere Tasks hinzufügen
$client->addTask('reverse', 'Hallo');
$client->addTask('reverse', 'Welt');
$client->addTask('uppercase', 'gearman');
// Alle Tasks parallel ausführen
if (!$client->runTasks()) {
echo 'Fehler beim Ausführen der Tasks: ' . $client->error() . PHP_EOL;
}Hintergrund-Job mit Job-Handle zur Statusabfrage
<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);
// Job im Hintergrund starten – blockiert nicht
$jobHandle = $client->doBackground('long_running_task', json_encode(['data' => 'payload']));
if ($client->returnCode() != GEARMAN_SUCCESS) {
echo 'Fehler beim Starten des Hintergrund-Jobs.' . PHP_EOL;
exit(1);
}
echo 'Job gestartet. Handle: ' . $jobHandle . PHP_EOL;
// Status des Jobs periodisch abfragen
do {
sleep(1);
$client->jobStatus($jobHandle, $isKnown, $isRunning, $numerator, $denominator);
if ($isRunning && $denominator > 0) {
$percent = round(($numerator / $denominator) * 100);
echo "Fortschritt: {$percent}%" . PHP_EOL;
}
} while ($isKnown && $isRunning);
echo 'Job abgeschlossen.' . PHP_EOL;// Wichtig · Fallstricke
Fehlerbehandlung: Nach jedem do*()-Aufruf sollte returnCode() geprüft werden. Bei einem Fehler liefert error() eine lesbare Fehlermeldung und getErrno() den numerischen Fehlercode.
Serialisierung: Gearman überträgt nur Strings als Job-Daten. Komplexe Datenstrukturen müssen vor der Übergabe serialisiert werden (z. B. mit json_encode() oder serialize()). Der Worker muss entsprechend deserialisieren.
Verbindungsmanagement: Mehrere Server können per addServer() oder addServers() hinzugefügt werden. Bei Ausfall eines Servers versucht der Client automatisch, einen anderen Server zu verwenden. Dennoch sollte im Produktionsbetrieb eine Ausnahmebehandlung implementiert werden.
Ressourcen: Bei lang laufenden PHP-Prozessen (z. B. CLI-Skripte) empfiehlt es sich, den Client regelmäßig neu zu instanziieren oder Verbindungsprobleme aktiv zu behandeln, um Ressourcenlecks zu vermeiden.