README

This is an Amp library for asynchronously monitor paths on your file system changes using various stategues.

It's been created to trigger code indexing in Phpactor.

• Promise based API.
• Capable of automatically selecting a supported watcher for the current environment.
• Provides realtime (e.g. inotify) watchers in addition to polling ones.
• Provides decorators for:
  • Including / excluding patterns.
  • Buffering notifications.
• Unitifed configuration for all watchers.

Usage

See bin/watch for an implementation, which looks something like this:

Loop::run(function () use () {

    $logger = // create a PSR logger
    $config = new WatcherConfig([$path]);
    $watcher = new PatternMatchingWatcher(
        new FallbackWatcher([
            new BufferedWatcher(new InotifyWatcher($config, $logger), 10),
            new FindWatcher($config, $logger),
            new PhpPollWatcher($config, $logger),
            new FsWatchWatcher($config, $logger)
        ], $logger),
        [ '/**/*.php' ],
        []
    );

    $process = yield $watcher->watch([$path]);

    while (null !== $file = yield $process->wait()) {
        fwrite(STDOUT, sprintf('[%s] %s (%s)'."\n", date('Y-m-d H:i:s.u'), $file->path(), $file->type()));
    }
});

Watchman

Watchman needs to be installed and will work on Linux, Mac and Windows.

use Phpactor\AmpFsWatch\Watcher\Watchman\WatchmanWatcher;

$watcher = new WatchmanWatcher($config, $logger);

Inotify

Use the Linux inotifywait binary to monitor for changes.

use Phpactor\AmpFsWatch\Watcher\Inotify\InotifyWatcher;

$watcher = new InotifyWatcher($config, $logger);
// ...

Fswatch

Unstable: This watcher has not been extensively tested.

FsWatch is a cross-platform (Linux,Mac,Windows) file watching utility which will automatically use the platforms native functionality when possible.

use Phpactor\AmpFsWatch\Watcher\FsWatch\FsWatchWatcher;

$watcher = new FsWatchWatcher($config, $logger);
// ...

Find

Use the find binary (Linux and Mac) to poll for file changes.

Poll for changes every second:

use Phpactor\AmpFsWatch\Watcher\Find\FindWatcher;

$watcher = new FindWatcher($config, $logger);
// ...

Note that while this should work on GNU and BSD variants of find it may not work on other variants due to being invoked with -newerxy switch, which is not in the POSIX standard.

PHP Poll

This is the slowest and most resource intensive option but it should work on all environments.

use Phpactor\AmpFsWatch\Watcher\Find\FindWatcher;

$watcher = new PhpPollWatcher($config, $logger);
// ...

Fallback

The fallback watcher will automatically select the first supported watcher on the current system:

use Phpactor\AmpFsWatch\Watcher\Fallback\FallbackWatcher;

$watcher = new FallbackWatcher(
    [
        new InotifyWatcher($logger),
        new FindWatcher(500, $logger)
    ]
    $logger
);
// ...

Contributing

This package is open source and welcomes contributions! Feel free to open a pull request on this repository.

Support

• Create an issue on the main Phpactor repository.
• Join the #phpactor channel on the Slack Symfony Devs channel.