stomp_ack — Funktion · PHP-Referenz

Signatur

stomp_ack(resource $link, array|object $msg, array $headers = []): bool

Beschreibung

stomp_ack() ist die prozedurale Variante der STOMP-Erweiterung und bestätigt den Empfang einer zuvor abonnierten Nachricht gegenüber dem Message-Broker. Im STOMP-Protokoll ist eine explizite Bestätigung (ACK) erforderlich, wenn das Abonnement im Modus client oder client-individual eingerichtet wurde. Ohne ein ACK geht der Broker davon aus, dass die Nachricht nicht verarbeitet wurde, und kann sie erneut zustellen.

Die Funktion akzeptiert als zweiten Parameter entweder das empfangene Nachrichten-Objekt direkt oder ein Array mit den relevanten Header-Informationen (z. B. message-id). Über den optionalen dritten Parameter können zusätzliche STOMP-Header übergeben werden, wie etwa eine Transaktions-ID, wenn die Bestätigung innerhalb einer Transaktion erfolgen soll.

Diese Funktion eignet sich besonders in Nachrichtenverarbeitungs-Pipelines, bei denen eine zuverlässige Zustellung sichergestellt werden muss – etwa bei der Verarbeitung von Bestellungen, Zahlungen oder anderen kritischen Geschäftsprozessen. Erst nach einem erfolgreichen ACK entfernt der Broker die Nachricht aus der Warteschlange.

Als objektorientierte Alternative steht die Methode Stomp::ack() zur Verfügung, die dieselbe Funktionalität bietet.

Parameter

Name	Typ	Default	Beschreibung
$link Pflicht	resource		Eine aktive STOMP-Verbindungsressource, die zuvor mit `stomp_connect()` erstellt wurde.
$msg Pflicht	array\|object		Die zu bestätigende Nachricht. Kann das Nachrichten-Objekt aus `stomp_read_frame()` oder ein assoziatives Array mit den benötigten Header-Feldern (insbesondere `message-id`) sein.
$headers	array	[]	Optionale zusätzliche STOMP-Header als assoziatives Array, z. B. eine Transaktions-ID: `['transaction' => 'tx1']`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Bestätigung erfolgreich an den Broker gesendet wurde, andernfalls false. Bei einem Fehler kann stomp_error() zur Fehlerdiagnose verwendet werden.

Beispiele

Einfaches ACK nach dem Lesen einer Nachricht

<?php
$stomp = stomp_connect('tcp://localhost:61613');

if (!$stomp) {
    die('Verbindung fehlgeschlagen: ' . stomp_connect_error());
}

// Abonnement im 'client'-Modus – ACK ist erforderlich
stomp_subscribe($stomp, '/queue/bestellungen', ['ack' => 'client']);

// Nachricht lesen
$frame = stomp_read_frame($stomp);

if ($frame !== false) {
    echo 'Nachricht empfangen: ' . $frame->body . PHP_EOL;

    // Verarbeitung der Nachricht...

    // Empfang bestätigen
    if (stomp_ack($stomp, $frame)) {
        echo 'Nachricht erfolgreich bestätigt.' . PHP_EOL;
    } else {
        echo 'Fehler beim ACK: ' . stomp_error($stomp) . PHP_EOL;
    }
}

stomp_disconnect($stomp);

Nachricht empfangen: {"bestellung_id": 42} Nachricht erfolgreich bestätigt.

ACK innerhalb einer Transaktion

<?php
$stomp = stomp_connect('tcp://localhost:61613');

if (!$stomp) {
    die('Verbindung fehlgeschlagen: ' . stomp_connect_error());
}

stomp_subscribe($stomp, '/queue/zahlungen', ['ack' => 'client']);

$frame = stomp_read_frame($stomp);

if ($frame !== false) {
    // Transaktion starten
    stomp_begin($stomp, 'tx-zahlung-1');

    echo 'Verarbeite Zahlung: ' . $frame->body . PHP_EOL;

    // Zahlung verarbeiten...
    $erfolg = true; // Simuliertes Ergebnis

    if ($erfolg) {
        // ACK innerhalb der Transaktion bestätigen
        stomp_ack($stomp, $frame, ['transaction' => 'tx-zahlung-1']);
        stomp_commit($stomp, 'tx-zahlung-1');
        echo 'Transaktion committed.' . PHP_EOL;
    } else {
        stomp_abort($stomp, 'tx-zahlung-1');
        echo 'Transaktion abgebrochen.' . PHP_EOL;
    }
}

stomp_disconnect($stomp);

Verarbeite Zahlung: {"betrag": 99.99} Transaktion committed.

// Wichtig · Fallstricke

Wichtig: Ein ACK ist nur notwendig, wenn das Abonnement mit dem Header ack: client oder ack: client-individual erstellt wurde. Im Standard-Modus auto bestätigt der Broker Nachrichten automatisch beim Empfang – ein manuelles ACK hat dann keinen Effekt.

Die STOMP-Erweiterung ist nicht standardmäßig in PHP enthalten und muss über PECL installiert werden (pecl install stomp). Sie ist als experimentell eingestuft, weshalb sich die API zwischen Versionen ändern kann.

Wird eine Nachricht nicht innerhalb einer bestimmten Zeit bestätigt, kann der Broker – je nach Konfiguration – die Nachricht erneut zustellen. Dies sollte bei der Anwendungslogik berücksichtigt werden, um doppelte Verarbeitung zu vermeiden (Idempotenz).

Siehe auch

stomp_connect stomp_read_frame stomp_subscribe stomp_unsubscribe stomp_begin stomp_commit stomp_abort stomp_error stomp_nack