Download the PHP package spatie/file-system-watcher without Composer

Watch changes in the file system using PHP

This package allows you to react to all kinds of changes in the file system.

Here's how you can run code when a new file gets added.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

In your project, you should have the JavaScript package chokidar installed. You can install it via npm

or Yarn

Usage

Here's how you can start watching a directory and get notified of any changes.

You can pass as many directories as you like to path.

To start watching, call the start method. Note that the start method will never end. Any code after that will not be executed.

To make sure that the watcher keeps watching in production, monitor the script or command that starts it with something like Supervisord. See Supervisord example configuration below.

Detected the type of change

The $type parameter of the closure you pass to onAnyChange can contain one of these values:

• Watcher::EVENT_TYPE_FILE_CREATED: a file was created
• Watcher::EVENT_TYPE_FILE_UPDATED: a file was updated
• Watcher::EVENT_TYPE_FILE_DELETED: a file was deleted
• Watcher::EVENT_TYPE_DIRECTORY_CREATED: a directory was created
• Watcher::EVENT_TYPE_DIRECTORY_DELETED: a directory was deleted

Listening for specific events

To handle file systems events of a certain type, you can make use of dedicated functions. Here's how you would listen for file creations only.

These are the related available methods:

• onFileCreated(): accepts a closure that will get passed the new file path
• onFileUpdated(): accepts a closure that will get passed the updated file path
• onFileDeleted(): accepts a closure that will get passed the deleted file path
• onDirectoryCreated(): accepts a closure that will get passed the created directory path
• onDirectoryDeleted(): accepts a closure that will get passed the deleted directory path

Watching multiple paths

You can pass multiple paths to the paths method.

Performing multiple tasks

You can call onAnyChange, 'onFileCreated', ... multiple times. All given closures will be performed

Stopping the watcher gracefully

By default, the watcher will continue indefinitely when started. To gracefully stop the watcher, you can call shouldContinue and pass it a closure. If the closure returns a falsy value, the watcher will stop. The given closure will be executed every 0.5 second.

Change the speed of watcher

By default, the changes are tracked every 0.5 seconds, however you could change that.

Notice : there is no file watching based on polling going on.

Testing

Supervisord example configuration

Create a new Supervisord configuration to monitor a Laravel artisan command which calls the watcher. While using Supervisord, you must specicfy your Node.js and PHP executables in your command paramater: env PATH="/usr/local/bin" for Node.js, the absolute path to PHP and your project's path.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Freek Van der Herten
• All Contributors

Parts of this package are inspired by Laravel Octane

License

The MIT License (MIT). Please see License File for more information.