msg_receive — Funktion · PHP-Referenz

Signatur

msg_receive(SysvMessageQueue $queue, int $desired_message_type, int &$received_message_type, int $max_message_size, mixed &$message, bool $unserialize = true, int $flags = 0, int &$error_code = null): bool

Beschreibung

msg_receive() liest eine Nachricht aus der angegebenen System-V-Nachrichten-Warteschlange. Die Funktion entnimmt dabei eine Nachricht des gewünschten Typs ($desired_message_type) und schreibt den tatsächlichen Nachrichtentyp in die übergebene Referenzvariable $received_message_type. Der Nachrichteninhalt wird in $message gespeichert.

Standardmäßig wird der Inhalt der Nachricht automatisch mit unserialize() deserialisiert, was eine direkte Übergabe komplexer PHP-Datentypen (Arrays, Objekte) zwischen Prozessen ermöglicht. Wird $unserialize auf false gesetzt, wird der Rohstring zurückgeliefert, was für die Kommunikation mit Nicht-PHP-Prozessen nützlich ist.

Über den Parameter $flags lässt sich das Verhalten steuern: Mit MSG_IPC_NOWAIT kehrt die Funktion sofort zurück, falls keine passende Nachricht vorhanden ist, anstatt zu blockieren. MSG_EXCEPT bewirkt, dass alle Nachrichten außer dem angegebenen Typ gelesen werden, und MSG_NOERROR schneidet zu lange Nachrichten auf $max_message_size ab, anstatt einen Fehler zu erzeugen.

Diese Funktion steht nur auf Unix-ähnlichen Systemen zur Verfügung und eignet sich besonders für die Interprozesskommunikation (IPC) zwischen PHP-Prozessen oder zwischen PHP und anderen Programmen auf demselben Server.

Parameter

Name	Typ	Default	Beschreibung
$queue Pflicht	SysvMessageQueue		Ein Warteschlangen-Handle, das zuvor mit `msg_get_queue()` erstellt wurde.
$desired_message_type Pflicht	int		Der gewünschte Nachrichtentyp. Bei `0` wird die erste Nachricht der Warteschlange gelesen, unabhängig vom Typ. Ein positiver Wert liest Nachrichten dieses genauen Typs. Ein negativer Wert liest die Nachricht mit dem kleinsten Typ, der kleiner oder gleich dem Absolutbetrag ist.
$received_message_type Pflicht	int		Referenzvariable, in die der tatsächliche Typ der gelesenen Nachricht geschrieben wird.
$max_message_size Pflicht	int		Maximale Größe der Nachricht in Bytes. Ist die Nachricht größer, schlägt der Aufruf fehl (sofern nicht `MSG_NOERROR` gesetzt ist).
$message Pflicht	mixed		Referenzvariable, in die der Inhalt der empfangenen Nachricht geschrieben wird. Bei aktiviertem `$unserialize` kann dies ein beliebiger PHP-Datentyp sein.
$unserialize	bool	true	Gibt an, ob die Nachricht automatisch mit `unserialize()` deserialisiert werden soll. Auf `false` setzen, wenn mit Nicht-PHP-Prozessen kommuniziert wird.
$flags	int	0	Optionale Flags zur Verhaltenssteuerung: `MSG_IPC_NOWAIT`, `MSG_EXCEPT`, `MSG_NOERROR` (oder deren Kombination via bitweisem ODER).
$error_code	int	null	Referenzvariable, in die im Fehlerfall der systemseitige Fehlercode geschrieben wird (z. B. `MSG_ENOMSG` bei nicht vorhandener Nachricht mit `MSG_IPC_NOWAIT`).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück. Im Fehlerfall wird false zurückgegeben und $error_code mit dem entsprechenden Systemfehlercode befüllt.

Beispiele

Einfacher Nachrichtenempfang zwischen zwei Prozessen

<?php
// Warteschlange öffnen oder erstellen (gleicher Schlüssel wie beim Sender)
$key = ftok('/tmp/mq_demo', 'A');
$queue = msg_get_queue($key, 0666);

$messageType = 0; // Beliebigen Typ empfangen
$receivedType = 0;
$message = null;
$maxSize = 1024;

$success = msg_receive($queue, $messageType, $receivedType, $maxSize, $message);

if ($success) {
    echo "Empfangener Typ: " . $receivedType . "\n";
    echo "Nachricht: ";
    var_dump($message);
} else {
    echo "Fehler beim Empfangen der Nachricht.\n";
}

Empfangener Typ: 1 Nachricht: string(12) "Hallo Welt!"

Nicht-blockierender Empfang mit Fehlercode-Auswertung

<?php
$key = ftok('/tmp/mq_demo', 'A');
$queue = msg_get_queue($key, 0666);

$receivedType = 0;
$message = null;
$errorCode = 0;

// MSG_IPC_NOWAIT: Sofort zurückkehren, wenn keine Nachricht vorhanden
$success = msg_receive(
    $queue,
    1,          // Nur Typ 1 empfangen
    $receivedType,
    4096,
    $message,
    true,
    MSG_IPC_NOWAIT,
    $errorCode
);

if ($success) {
    echo "Nachricht empfangen: ";
    var_dump($message);
} elseif ($errorCode === MSG_ENOMSG) {
    echo "Keine Nachricht verfügbar – Warteschlange leer oder Typ nicht gefunden.\n";
} else {
    echo "Fehler: Errorcode = " . $errorCode . "\n";
}

// Warteschlange entfernen
msg_remove_queue($queue);

Keine Nachricht verfügbar – Warteschlange leer oder Typ nicht gefunden.

// Wichtig · Fallstricke

Plattformverfügbarkeit: msg_receive() ist nur auf Unix-/Linux-Systemen verfügbar (POSIX System V IPC). Unter Windows steht diese Funktion nicht zur Verfügung.

Sicherheit bei unserialize: Wird $unserialize auf true belassen und können Nachrichten von nicht vertrauenswürdigen Quellen stammen, besteht das Risiko von Objekt-Injection-Angriffen. In solchen Fällen $unserialize auf false setzen und den Rohstring selbst sicher verarbeiten.

Blockierendes Verhalten: Ohne MSG_IPC_NOWAIT blockiert die Funktion so lange, bis eine passende Nachricht verfügbar ist. In Produktionsanwendungen sollte deshalb ein Timeout-Mechanismus oder nicht-blockierender Modus in Betracht gezogen werden.

PHP-Erweiterung: Die Funktion erfordert, dass PHP mit --enable-sysvmsg kompiliert wurde. Seit PHP 8.0 ist der erste Parameter vom Typ SysvMessageQueue statt einer Ressource.

Siehe auch

msg_send msg_get_queue msg_remove_queue msg_stat_queue msg_set_queue