PHPackages                             vox/file-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. vox/file-watcher

ActiveLibrary

vox/file-watcher
================

0.1(7y ago)06MITPHPPHP >=7.1

Since May 31Pushed 7y ago1 watchersCompare

[ Source](https://github.com/jhonatanTeixeira/file-watcher)[ Packagist](https://packagist.org/packages/vox/file-watcher)[ RSS](/packages/vox-file-watcher/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

PHP Inotify File Watcher
========================

[](#php-inotify-file-watcher)

Installing
----------

[](#installing)

this library requires PHP 7.1+ and pecl inotify extension inotify

```
$ sudo pecl install inotify
$ composer require vox/file-watcher

```

Usage
-----

[](#usage)

Usage is simple, first configure the context:

```
use Vox\FileWatcher\FolderWatcherContext;
use Vox\FileWatcher\FolderWatcher;

$context = new FolderWatcherContext();
$context->blocking = true;  //if set to false, php will not block when readEvents is called, async code can be done
$context->recursive = true; //if set to true subfolders will be also watched,
                            //and so new subfolders will be automatically be watched
```

Then obtain the watcher instance:

```
$watcher = new FolderWatcher('/folder/to/watch', $context);
```

Now, all you need is the callback actions for each possible event, like this:

```
$watcher->onCreated(function (FileWatcherEvent $event, FolderWatcherContext $context) {
    //do something when a file is created
});
```

there are other events to be listened:

- onMoved
- onOpened
- onModified
- onClosed
- onDeleted

Finaly call the dispatch event method to listen to filesystem changes:

```
$watcher->dispatchEvents();
```

Note that, this operation will block untill an event occurs, and returns imediately as soon an filesystem event on the watched folder happens. This block can be avoided setting the context blocking property to false, that way, if no event ocurred between the watcher instancing and the call of this method an empty array will be returned

### The readEvents method

[](#the-readevents-method)

You may notice that the FolderWatcher class has a readEvents method, this method can be called in case you may need to get the events without dispatching the events. this method returns an array of Vox\\FileWatcher\\FileWatcherEvent, this class has various methods to help identify what is this event about:

- isDir
- isWatchedDir - returns true if this event refers to a dir wihch is currently beig watched
- isMovedFile
- isMovedFrom
- isMovedTo
- isCreated
- isModified
- isDeleted
- isOpened
- isClosed
- getOriginPath - if its a moved file, get the former path as SplFileInfo instance
- getPath - the file path as SplFileInfo instance
- getCookie - if the event has a cookie, than its a moved file, the cookie is what binds the moved from and moved to events

Note: not all the movedTo files has a origin path, only those that are moved between watched dirs, when a file comes from a directory wihch is not being watched it will have no moved from event, therefore no originPath

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

2900d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2b151b09844eedb0fc2a4a3f5ff6766ec85d3bd1f3c5553e0c117ee279ede952?d=identicon)[jhonatanTeixeira](/maintainers/jhonatanTeixeira)

---

Top Contributors

[![jhonatanTeixeira](https://avatars.githubusercontent.com/u/1003279?v=4)](https://github.com/jhonatanTeixeira "jhonatanTeixeira (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

PHPackages © 2026

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