PHPackages                             spatie/file-system-watcher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. spatie/file-system-watcher

ActiveLibrary[File & Storage](/categories/file-storage)

spatie/file-system-watcher
==========================

Watch changes in the file system using PHP

1.2.1(5mo ago)2502.1M—8.2%2515MITPHPPHP ^8.3CI passing

Since May 4Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/spatie/file-system-watcher)[ Packagist](https://packagist.org/packages/spatie/file-system-watcher)[ Docs](https://github.com/spatie/file-system-watcher)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-file-system-watcher/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (11)Used By (15)

Watch changes in the file system using PHP
==========================================

[](#watch-changes-in-the-file-system-using-php)

[![Latest Version on Packagist](https://camo.githubusercontent.com/fbdd4b8e0bd9b518b58833711461ec0ee3a0fef8c636f85177aed904c42866d7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f66696c652d73797374656d2d776174636865722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/file-system-watcher)[![Tests](https://github.com/spatie/file-system-watcher/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/file-system-watcher/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/66f32c40abce681f2271a53d6f78b681284561783bebaa6eab9af1182c92ee59/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f66696c652d73797374656d2d776174636865722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/file-system-watcher)

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.

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->onFileCreated(function (string $newFilePath) {
        // do something...
    })
    ->start();
```

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/d573bbbfe2209ecfc8e7545df2c5d514c49e8fb417bf6fac03b9342b8e2d4611/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f66696c652d73797374656d2d776174636865722e6a70673f743d31)](https://spatie.be/github-ad-click/file-system-watcher)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

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](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require spatie/file-system-watcher
```

In your project, you should have the JavaScript package [`chokidar`](https://github.com/paulmillr/chokidar) installed. You can install it via npm

```
npm install chokidar
```

or Yarn

```
yarn add chokidar
```

Usage
-----

[](#usage)

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

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->onAnyChange(function (string $type, string $path) {
        if ($type === Watch::EVENT_TYPE_FILE_CREATED) {
            echo "file {$path} was created";
        }
    })
    ->start();
```

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](http://supervisord.org). See [Supervisord example configuration](#supervisord-example-configuration) below.

### Detected the type of change

[](#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

[](#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.

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->onFileCreated(function (string $newFilePath) {
        // do something...
    });
```

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

[](#watching-multiple-paths)

You can pass multiple paths to the `paths` method.

```
use Spatie\Watcher\Watch;

Watch::paths($directory, $anotherDirectory);
```

### Performing multiple tasks

[](#performing-multiple-tasks)

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

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->onFileCreated(function (string $newFilePath) {
        // do something on file creation...
    })
    ->onFileCreated(function (string $newFilePath) {
        // do something else on file creation...
    })
    ->onAnyChange(function (string $type, string $path) {
        // do something...
    })
    ->onAnyChange(function (string $type, string $path) {
        // do something else...
    })
    // ...
```

### Stopping the watcher gracefully

[](#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.

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->shouldContinue(function () {
        // return true or false
    })
    // ...
```

### Change the speed of watcher

[](#change-the-speed-of-watcher)

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

```
use Spatie\Watcher\Watch;

Watch::path($directory)
    ->setIntervalTime(1000000) //unit is microsecond therefore -> 0.1s
    // ...rest of your methods
```

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

Testing
-------

[](#testing)

```
composer test
```

Supervisord example configuration
---------------------------------

[](#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.

```
[program:watch]
process_name=%(program_name)s
directory=/your/project
command=env PATH="/usr/local/bin" /absolute/path/to/php /your/project/artisan watch-for-files
autostart=true
autorestart=false
user=username
redirect_stderr=true
stdout_logfile=/your/project/storage/logs/watch.log
stopwaitsecs=3600

```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

Parts of this package are inspired by [Laravel Octane](https://github.com/laravel/octane)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance70

Regular maintenance activity

Popularity60

Solid adoption and visibility

Community32

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 75.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~185 days

Recently: every ~344 days

Total

10

Last Release

174d ago

Major Versions

0.0.3 → 1.0.02021-05-06

PHP version history (2 changes)0.0.1PHP ^8.0

1.2.1PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (64 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (5 commits)")[![WyattCast44](https://avatars.githubusercontent.com/u/17957937?v=4)](https://github.com/WyattCast44 "WyattCast44 (3 commits)")[![alexmanase](https://avatars.githubusercontent.com/u/10696975?v=4)](https://github.com/alexmanase "alexmanase (2 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![ryatkins](https://avatars.githubusercontent.com/u/1211767?v=4)](https://github.com/ryatkins "ryatkins (2 commits)")[![Stevemoretz](https://avatars.githubusercontent.com/u/27680142?v=4)](https://github.com/Stevemoretz "Stevemoretz (2 commits)")[![thecaliskan](https://avatars.githubusercontent.com/u/13554944?v=4)](https://github.com/thecaliskan "thecaliskan (2 commits)")[![joeworkman](https://avatars.githubusercontent.com/u/225628?v=4)](https://github.com/joeworkman "joeworkman (1 commits)")[![richardfrankza](https://avatars.githubusercontent.com/u/17523844?v=4)](https://github.com/richardfrankza "richardfrankza (1 commits)")[![angeljqv](https://avatars.githubusercontent.com/u/79208641?v=4)](https://github.com/angeljqv "angeljqv (1 commits)")

---

Tags

spatiefile-system-watcher

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/spatie-file-system-watcher/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-file-system-watcher/health.svg)](https://phpackages.com/packages/spatie-file-system-watcher)
```

###  Alternatives

[spatie/image

Manipulate images with an expressive API

1.4k54.4M138](/packages/spatie-image)[spatie/db-dumper

Dump databases

1.2k25.9M69](/packages/spatie-db-dumper)[spatie/laravel-health

Monitor the health of a Laravel application

86910.0M83](/packages/spatie-laravel-health)[spatie/flysystem-dropbox

Flysystem Adapter for the Dropbox v2 API

3644.6M68](/packages/spatie-flysystem-dropbox)[spatie/laravel-google-cloud-storage

Google Cloud Storage filesystem driver for Laravel

2408.9M13](/packages/spatie-laravel-google-cloud-storage)[spatie/typescript-transformer

This is my package typescript-transformer

3706.5M16](/packages/spatie-typescript-transformer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)