PHPackages                             steve-moretz/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. steve-moretz/file-system-watcher

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

steve-moretz/file-system-watcher
================================

Watch changes in the file system using PHP

1.0.2(4y ago)01.3k1MITPHPPHP ^7.0|^8.0

Since May 4Pushed 4y agoCompare

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

READMEChangelogDependencies (5)Versions (8)Used By (1)

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

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

```
use Spatie\Watcher\Watch;

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

Support
-------

[](#support)

Php 7 | 8

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.

### 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(100) //microseconds
    // ...
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

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

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

[](#contributing)

Please see [CONTRIBUTING](.github/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

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 83.6% 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 ~57 days

Recently: every ~72 days

Total

6

Last Release

1543d ago

Major Versions

0.0.3 → 1.0.02021-05-06

PHP version history (2 changes)0.0.1PHP ^8.0

1.0.2PHP ^7.0|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4d558b19d46728340279509118d25ebbd92115e4048f541c00c3f9f62672f1e0?d=identicon)[Stevemoretz](/maintainers/Stevemoretz)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (46 commits)")[![Stevemoretz](https://avatars.githubusercontent.com/u/27680142?v=4)](https://github.com/Stevemoretz "Stevemoretz (5 commits)")[![WyattCast44](https://avatars.githubusercontent.com/u/17957937?v=4)](https://github.com/WyattCast44 "WyattCast44 (3 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (1 commits)")

---

Tags

spatiefile-system-watcher

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[spatie/file-system-watcher

Watch changes in the file system using PHP

2502.1M17](/packages/spatie-file-system-watcher)[spatie/image

Manipulate images with an expressive API

1.4k54.4M137](/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

85810.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.9M12](/packages/spatie-laravel-google-cloud-storage)

PHPackages © 2026

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