andrewmackrodt/fsnotify

Event based file system watcher for PHP

v0.1.1 2024-09-18 08:54 UTC

Requires

• php: ^7.1|>=8.0
• amphp/process: ^1.1
• amphp/react-adapter: dev-promise
• composer/xdebug-handler: ^1.3
• react/event-loop: ^1.1
• symfony/event-dispatcher: ^4.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.15
• mockery/mockery: ^1.2
• phpunit/phpunit: ^8.2
• sempro/phpunit-pretty-print: ^1.0

MIT

• Andrew Mackrodt

README

Event based file system watcher for PHP. FsNotify is fully† async and event based using Amp and Symfony\EventDispatcher.

† excluding stat operations to determine file metadata

Usage

Quick start

<?php

use Denimsoft\FsNotify\Event\FileEvent;
use Denimsoft\FsNotify\FsNotifyBuilder;

require_once __DIR__ . '/vendor/autoload.php';

$fsNotify = (new FsNotifyBuilder())
    ->addWatcher(__DIR__ . '/src', true)
    ->getBuilder()
    ->addChangeListener(function (FileEvent $event) {
        echo sprintf(
                "[%s] (%s) \"%s\" %s\n",
                date('c'),
                $event->getEventName(),
                $event->getFilepath(),
                json_encode($event->getMetadata())
            );
    })
    ->createFsNotify();

$fsNotify->start();

Advanced usage

FsNotify supports monitoring multiple paths with configurable callbacks and filters. See the examples directory for complete usage:

• examples/standard.php
• examples/async.php
• examples/advanced.php
• examples/laravel-ide-helper.php

This library was developed with the laravel-ide-helper use case in mind, it highlights a moderately complicated yet useful usage scenario.

Adapters

PhpAdapter - fallback adapter if no other adapters are supported. PhpAdapter uses file polling to detect changes. The adapter defaults to a configurable polling interval of 1 second. It is sufficient for monitoring a small amount of files.

FswatchAdapter - fswatch requires the GNU CLI tool fswatch, it's more performant than PhpAdapter and detects file changes almost instantaneously. It is preferred in most cases but can be slow to propagate large amounts of file deletions (such as deleting the vendor or node_modules folder of a PHP or JavaScript project respectively); however, this use case is considered atypical and should not affect most users. It also does not initially recurse into a copied or moved directory but this is once again not typically a requirement when watching for changes to Laravel models or static asset directories before executing a third-party tool.