Signatur
Beschreibung
inotify_add_watch() registriert eine Überwachung (Watch) für eine Datei oder ein Verzeichnis bei einer zuvor mit inotify_init() erstellten Inotify-Instanz. Sobald eines der über $mask definierten Ereignisse eintritt (z. B. Datei erstellt, gelesen oder gelöscht), können diese Ereignisse über inotify_read() ausgelesen werden.
Die Funktion steht nur auf Linux-Systemen zur Verfügung und setzt die PECL-Erweiterung inotify voraus. Sie ist besonders nützlich für Dateiüberwachungs-Szenarien wie automatisches Deployment, Cache-Invalidierung oder das Reagieren auf Konfigurationsänderungen, ohne dass aktives Polling nötig ist.
Wird inotify_add_watch() für einen Pfad aufgerufen, der bereits überwacht wird, so wird der vorhandene Watch aktualisiert (Masken werden zusammengeführt) und derselbe Watch-Deskriptor zurückgegeben. So lässt sich die Überwachung schrittweise erweitern.
Der zurückgegebene Watch-Deskriptor (Integer) wird von inotify_rm_watch() benötigt, um die Überwachung wieder zu entfernen. Er ist außerdem in jedem von inotify_read() gelieferten Ereignis-Array als Feld wd enthalten, sodass das auslösende Watch identifiziert werden kann.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $inotify_instance Pflicht | resource | Eine Inotify-Instanz, die mit inotify_init() erstellt wurde. |
|
| $pathname Pflicht | string | Absoluter oder relativer Pfad zur Datei oder zum Verzeichnis, das überwacht werden soll. | |
| $mask Pflicht | int | Bitmaske aus IN_*-Konstanten, die festlegt, welche Ereignisse überwacht werden. Beispiele: IN_CREATE, IN_DELETE, IN_MODIFY, IN_MOVED_FROM, IN_MOVED_TO. Mehrere Ereignisse werden mit dem bitweisen OR-Operator (|) kombiniert. |
Rückgabewert
false zurückgegeben.Beispiele
Verzeichnis auf neue Dateien und Löschungen überwachen
<?php
$inotify = inotify_init();
// Verzeichnis auf Erstellungen und Löschungen überwachen
$watchDescriptor = inotify_add_watch(
$inotify,
'/var/www/uploads',
IN_CREATE | IN_DELETE
);
echo "Watch-Deskriptor: " . $watchDescriptor . PHP_EOL;
// Auf Ereignisse warten und verarbeiten
while (true) {
$events = inotify_read($inotify);
if ($events !== false) {
foreach ($events as $event) {
if ($event['mask'] & IN_CREATE) {
echo "Neue Datei erstellt: " . $event['name'] . PHP_EOL;
}
if ($event['mask'] & IN_DELETE) {
echo "Datei gelöscht: " . $event['name'] . PHP_EOL;
}
}
}
}
inotify_rm_watch($inotify, $watchDescriptor);
fclose($inotify);Mehrere Verzeichnisse gleichzeitig überwachen
<?php
$inotify = inotify_init();
$paths = [
'/etc/nginx/sites-enabled',
'/etc/php/8.2/fpm/pool.d',
];
$watches = [];
foreach ($paths as $path) {
$wd = inotify_add_watch($inotify, $path, IN_MODIFY | IN_CREATE | IN_DELETE);
$watches[$wd] = $path;
echo "Überwache: $path (WD: $wd)" . PHP_EOL;
}
// Auf Ereignisse warten
$events = inotify_read($inotify);
if ($events !== false) {
foreach ($events as $event) {
$dir = $watches[$event['wd']] ?? 'Unbekannt';
echo "Änderung in '$dir': " . $event['name'] . " (Maske: " . $event['mask'] . ")" . PHP_EOL;
}
}
// Alle Watches entfernen
foreach (array_keys($watches) as $wd) {
inotify_rm_watch($inotify, $wd);
}
fclose($inotify);// Wichtig · Fallstricke
Plattformabhängigkeit: inotify_add_watch() ist ausschließlich auf Linux verfügbar. Das Inotify-Subsystem steht ab Kernel 2.6.13 zur Verfügung. Für macOS oder Windows existieren keine entsprechenden Äquivalente in dieser Erweiterung.
Ressourcenlimit: Die maximale Anzahl gleichzeitiger Watches pro Instanz ist systemseitig begrenzt und kann über /proc/sys/fs/inotify/max_user_watches eingesehen und angepasst werden. Bei Überschreitung schlägt inotify_add_watch() fehl.
Blockierendes Lesen: inotify_read() blockiert standardmäßig, bis ein Ereignis eintrifft. Um nicht-blockierendes Verhalten zu erzielen, kann die Inotify-Instanz mit stream_set_blocking($inotify, false) in den nicht-blockierenden Modus versetzt werden.
Verzeichnis vs. Datei: Bei der Überwachung eines Verzeichnisses enthält das Ereignis-Feld name den Dateinamen der betroffenen Datei innerhalb des Verzeichnisses. Bei der Überwachung einer einzelnen Datei ist name leer.