README

This package allows watching folders for any change and being notified when it happens.

PHP does not implement native filesystem watchers so the package basically maps the content of the watched folders and rescan them regularly to identify any potential change.

This package has been initially developed to help monitoring file changes within a website static generator tool and improve workflow.

Requirements

This package requires PHP 8.1+ but has no other dependency.

Installation

Use Composer to install the package:

composer require chsxf/folder-watcher

How to Use

This package has been designed to be easy to use but flexible.

Instantiation

require_once('vendor/autoload.php');

use chsxf\FolderWatcher\Runner;

// Instantiates the runner and configures the watched folders
// A second int parameter is available to set the refresh interval in milliseconds (set by default at 50 ms)
$runner = new Runner(['assets', 'templates']);

Reponders

Changes are reported to "responders". A responder can be any object implementing the IWatchResponder interface or a simple callable that accepts an array as its single parameter.

Using a callable allows you respond to changes only and you won't receive any other messages that the IWatchResponder interface supports, like a notification at the start of a watch loop.

In both cases, changes are reported as an array of WatchChange objects.

function responderCallable(array $changes) {
    // Do something with the array
}

$runner->addResponder(responderCallable(...));

Watching

When everything is configured, you can start watching for changes.

Important

This will effectively send your PHP process in an infinite loop, interrupted periodically by sleeping for how many milliseconds you've set as the refresh interval, or to notify your responders of any changes.

$runner->watch();

Stopping

$runner->stop();

Support

This package is under active development.

However, support is not guaranteed in any way. Pull requests or issues are welcomed but you may wait for some time before getting any answer.

chsxf / folder-watcher

Maintainers

Details