Signatur
Beschreibung
sapi_windows_set_ctrl_handler() registriert eine Callback-Funktion, die aufgerufen wird, wenn der Benutzer in einem Windows-Konsolenfenster ein CTRL-Ereignis auslöst – typischerweise CTRL+C (Signal PHP_WINDOWS_EVENT_CTRL_C) oder CTRL+BREAK (Signal PHP_WINDOWS_EVENT_CTRL_BREAK). Die Funktion ist ausschließlich unter Windows und nur im CLI-SAPI verfügbar.
Der übergebene Handler erhält als einziges Argument den Ereignistyp (eine Integer-Konstante) und kann so zwischen den verschiedenen CTRL-Ereignissen unterscheiden. Gibt der Handler true zurück, gilt das Ereignis als behandelt und der Standardprozess (Prozessbeendigung) wird unterdrückt. Gibt er false zurück oder ist kein Handler registriert, führt Windows die Standardaktion aus.
Wird null als $handler übergeben und $add auf false gesetzt, entfernt PHP den zuletzt registrierten Handler. Mit $add = true wird ein neuer Handler hinzugefügt; es können mehrere Handler gestapelt werden. Mit $add = false wird der angegebene Handler aus der internen Liste entfernt.
Typische Anwendungsfälle sind lang laufende CLI-Prozesse, die bei einem Abbruchsignal sauber Ressourcen freigeben, Transaktionen rollbacken oder Status speichern sollen, bevor der Prozess endet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handler Pflicht | callable|null | Eine Callback-Funktion, die beim Eintreten eines CTRL-Ereignisses aufgerufen wird. Sie erhält den Ereignistyp (PHP_WINDOWS_EVENT_CTRL_C oder PHP_WINDOWS_EVENT_CTRL_BREAK) als int. Gibt sie true zurück, wird die Standard-Systemreaktion unterdrückt. null ist nur in Kombination mit $add = false zulässig, um alle Handler zu entfernen. |
|
| $add | bool | true | Wenn true (Standard), wird der Handler zur internen Handler-Liste hinzugefügt. Wenn false, wird der angegebene Handler aus der Liste entfernt. |
Rückgabewert
true zurück, wenn der Handler erfolgreich gesetzt oder entfernt wurde, andernfalls false (z. B. wenn die Funktion außerhalb des CLI-SAPIs oder auf einem Nicht-Windows-System aufgerufen wird).Beispiele
CTRL+C abfangen und sauber beenden
<?php
$running = true;
sapi_windows_set_ctrl_handler(function (int $event) use (&$running): bool {
if ($event === PHP_WINDOWS_EVENT_CTRL_C) {
echo PHP_EOL . 'CTRL+C empfangen – beende sauber...' . PHP_EOL;
$running = false;
return true; // Standard-Abbruch unterdrücken
}
return false;
});
echo 'Prozess läuft. Drücke CTRL+C zum Beenden.' . PHP_EOL;
while ($running) {
echo '.';
sleep(1);
}
echo 'Ressourcen freigegeben. Auf Wiedersehen!' . PHP_EOL;Handler wieder entfernen
<?php
$handler = function (int $event): bool {
echo 'Ereignis: ' . $event . PHP_EOL;
return true;
};
// Handler registrieren
sapi_windows_set_ctrl_handler($handler);
echo 'Handler registriert.' . PHP_EOL;
sleep(3);
// Handler wieder entfernen
sapi_windows_set_ctrl_handler($handler, false);
echo 'Handler entfernt. CTRL+C beendet den Prozess jetzt normal.' . PHP_EOL;// Wichtig · Fallstricke
Plattformabhängigkeit: Diese Funktion ist ausschließlich unter Windows und nur im CLI-SAPI verfügbar. Auf anderen Plattformen oder in anderen SAPIs (Apache, FPM etc.) gibt sie false zurück und hat keine Wirkung. Für POSIX-Systeme sollte stattdessen pcntl_signal() verwendet werden.
Rückgabewert des Handlers: Der Handler wird in einem separaten Thread von Windows aufgerufen. Es ist wichtig, im Handler keine nicht-threadsicheren Operationen durchzuführen. Gibt der Handler false zurück oder löst er eine Ausnahme aus, wird die Standard-Windows-Aktion (Prozessbeendigung) weiterhin ausgeführt.
Verfügbare Konstanten: PHP_WINDOWS_EVENT_CTRL_C (Wert 0) und PHP_WINDOWS_EVENT_CTRL_BREAK (Wert 1) sind die einzigen derzeit definierten Ereignistypen.