PHPackages seregazhuk/php-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. [CLI & Console](/categories/cli) 4. / 5. seregazhuk/php-watcher ActiveLibrary[CLI & Console](/categories/cli) seregazhuk/php-watcher ====================== Automatically restart PHP application once the source code changes v0.8.0(6mo ago)394137.8k↓25.3%324MITPHPPHP >=8.1 Since Oct 4Pushed 6mo ago15 watchersCompare [ Source](https://github.com/seregazhuk/php-watcher)[ Packagist](https://packagist.org/packages/seregazhuk/php-watcher)[ RSS](/packages/seregazhuk-php-watcher/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (13)Versions (15)Used By (4) PHP-watcher =========== [](#php-watcher) [![PHP Version](https://camo.githubusercontent.com/0fb7e6fb4cea38f928cdaab3d0342a4ef67a10d488cbffdd569a974fc14a1eef/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7365726567617a68756b2f7068702d776174636865722e737667)](https://php.net/)[![Total Downloads](https://camo.githubusercontent.com/7b6680417b7e45801e6b445007da813f99dde3e0dd830ba87402dd77e9a8bdce/68747470733a2f2f706f7365722e707567782e6f72672f7365726567617a68756b2f7068702d776174636865722f646f776e6c6f616473)](https://packagist.org/packages/seregazhuk/php-watcher) [![Latest Stable Version](https://camo.githubusercontent.com/45cb1b342ff3dadcb269628e3a253145948533bcae29ae8b1a1d37b21315f7d4/68747470733a2f2f706f7365722e707567782e6f72672f7365726567617a68756b2f7068702d776174636865722f762f737461626c65)](https://packagist.org/packages/seregazhuk/php-watcher)[![Latest Version](https://camo.githubusercontent.com/82b6e2401d5e2f90d3e5acc639a22076777d2e1ed4a767705861f450d2eb73ac/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7365726567617a68756b2f7068702d776174636865722e737667)](https://packagist.org/packages/seregazhuk/php-watcher)[![Latest Unstable Version](https://camo.githubusercontent.com/80ec53310a28d9903773305765456dded36889d4bcd17ef6a50a9dc9f8466bcb/68747470733a2f2f706f7365722e707567782e6f72672f7365726567617a68756b2f7068702d776174636865722f762f756e737461626c65)](https://packagist.org/packages/seregazhuk/php-watcher) [![License](https://camo.githubusercontent.com/47b3cdaf41df2ab1b1945857d7789fb2b6a08f7dc7b64d729f6b5f6d9516057b/68747470733a2f2f706f7365722e707567782e6f72672f7365726567617a68756b2f7068702d776174636865722f6c6963656e7365)](https://packagist.org/packages/seregazhuk/php-watcher) [![watcher logo](images/watcher.gif)](images/watcher.gif) PHP-watcher helps develop long-running PHP applications by automatically restarting them when file changes in the directory are detected. Here's how it looks like: [![watcher screenshot](images/demo.svg)](images/demo.svg) PHP-watcher does not require any additional changes to your code or method of development. `php-watcher` is a replacement wrapper for `php`, to use PHP -watcher replace the word `php` in the command line when executing your script. **Table of contents** - [Installation](#installation) - [Usage](#usage) - [Config files](#config-files) - [Monitoring multiple directories](#monitoring-multiple-directories) - [Specifying extension watch list](#specifying-extension-watch-list) - [Ignoring files](#ignoring-files) - [Delaying restarting](#delaying-restarting) - [Default executable](#default-executable) - [Gracefully reloading down your script](#gracefully-reloading-down-your-script) - [Automatic restart](#automatic-restart) - [Performance](#performance) - [Spinner](#spinner) Installation ------------ [](#installation) You can install this package globally like this: ``` composer global require seregazhuk/php-watcher ``` After that phpunit-watcher watch can be run in any directory on your system. Alternatively, you can install the package locally as a dev dependency in your project: ``` composer require seregazhuk/php-watcher --dev ``` Locally installed you can run it with `vendor/bin/php-watcher`. Usage ----- [](#usage) All the examples assume you've installed the package globally. If you opted for the local installation prepend `vendor/bin/` everywhere where `php-watcher` is mentioned. PHP-watcher wraps your application, so you can pass all the arguments you would normally pass to your app: ``` php-watcher [your php app] ``` Using PHP-Watcher is simple. If your application accepts a host and port as the arguments, I can start it using option `--arguments`: ``` php-watcher server.php --arguments localhost --arguments 8080 ``` Any output from this script is prefixed with `[php-watcher]`, otherwise all output from your application, errors included, will be echoed out as expected. Config files ------------ [](#config-files) PHP-Watcher supports customization of its behavior with config files. The file for options may be named `.php-watcher.yml`, `php-watcher.yml` or `php-watcher.yml.dist`. The tool will look for a file in the current working directory in that order. An alternative local configuration file can be specified with the `--config ` option. The specificity is as follows, so that a command line argument will always override the config file settings: - command line arguments - local config A config file can take any of the command line arguments, for example: ``` watch: - src - config extensions: - php - yml ignore: - tests ``` Monitoring multiple directories ------------------------------- [](#monitoring-multiple-directories) By default, PHP-Watcher monitors the current working directory. If you want to take control of that option, use the `--watch` option to add specific paths: ``` php-watcher --watch src --watch config server.php ``` Now PHP-Watcher will only restart if there are changes in the `./src` or `./config ` directories. By default traverses sub-directories, so there's no need to explicitly include them. Specifying extension watch list ------------------------------- [](#specifying-extension-watch-list) By default, PHP-Watcher looks for files with the `.php` extension. If you use the `--ext` option and monitor `app,yml` PHP-Watcher will monitor files with the extension of `.php` and `.yml`: ``` php-watcher server.php --ext=php,yml ``` Now PHP-Watcher will restart on any changes to files in the directory (or subdirectories) with the extensions `.php`, `.yml`. Ignoring files -------------- [](#ignoring-files) By default, PHP-Watcher will only restart when a `.php` file changes. In some cases you may want to ignore some specific files, directories or file patterns, to prevent PHP-Watcher from prematurely restarting your application. This can be done via the command line: ``` php-watcher server.php --ignore public/ --ignore tests/ ``` Or specific files can be ignored: ``` php-watcher server.php --ignore src/config.php ``` Patterns can also be ignored (but be sure to quote the arguments): ``` php-watcher server.php --ignore 'src/config/*.php' ``` Note that by default, PHP-Watcher ignores all *dot* and VCS files. Delaying restarting ------------------- [](#delaying-restarting) In some situations, you may want to wait until a number of files have changed . The timeout before checking for new file changes is 1 second. If you're uploading a number of files and it's taking some number of seconds, this could cause your app to restart multiple times unnecessarily. To add an extra throttle, or delay restarting, use the `--delay` option: ``` php-watcher server.php --delay 10 ``` For more precision, use a float: ``` php-watcher server.php --delay 2.5 ``` Default executable ------------------ [](#default-executable) By default, PHP-Watcher uses `php` bin executable to run your scripts. If you want to provide your own executable use `--exec` option or `executable` param in config file. This is particularly useful if you're working with several PHP versions. ``` executable: php ``` or using CLI: ``` php-watcher server.php --exec php7 ``` ### Running non-php scripts [](#running-non-php-scripts) PHP-Watcher can also be used to execute and monitor other non-php programs. For example, you can use PHP-Watcher to listen to `*.js` files and use `node` executable to run them: ``` php-watcher server.js --exec node --watch app --ext=js ``` The command above uses NodeJS to start `server.js` and then listens to changes in `app` directory. Gracefully reloading down your script ------------------------------------- [](#gracefully-reloading-down-your-script) It is possible to have PHP-watcher send any signal that you specify to your application. ``` php-watcher --signal SIGTERM server.php ``` Your application can handle the signal as follows: ``` declare(ticks = 1); pcntl_signal(SIGTERM, 'terminationHandler'); function terminationHandler() { // ... } ``` By default PHP-watcher sends `SIGINT` signal. Automatic restart ----------------- [](#automatic-restart) PHP-watcher was originally written to restart long-running processes such as web servers, but it also supports apps that cleanly exit. If your script exits cleanly, the watcher will continue to monitor the directory (or directories) and restart the script if there are any changes. If the script crashes PHP-watcher will notify you about that. [![app exit](images/exit.svg)](images/exit.svg) Performance ----------- [](#performance) The watcher can use different strategies to monitor your file system changes. Under the hood it detects the environment and chooses the best suitable strategy. ### Fswatch (OSX only) [](#fswatch-osx-only) [FsWatch](https://github.com/emcrisostomo/fswatch) is a cross-platform (Linux,Mac,Windows) file change monitor that will automatically use the platforms native functionality when possible. Under the hood the filesystem notifies us when any changes occur. Currently, it [doesn't work correctly on Linux](https://github.com/emcrisostomo/fswatch/issues/247). If your system is OSx and has fswatch installed, this strategy will be used. **Has not been extensively tested.** ### Chokidar [](#chokidar) [Chokidar](https://github.com/paulmillr/chokidar) is a JavaScript package for watching file and directory changes. At first run the watcher will check if Node.js is available in the system. If it is, it will install chokidar into the project. Spinner ------- [](#spinner) By default, the watcher outputs a nice spinner which indicates that the process is running and watching your files. But if your system doesn't support ansi coded the watcher will try to detect it and disable the spinner. Or you can always disable the spinner manually with option '--no-spinner': ``` php-watcher server.php --no-spinner ``` License ======= [](#license) MIT ### Health Score 55 — FairBetter than 98% of packages Maintenance66 Regular maintenance activity Popularity50 Moderate usage in the ecosystem Community27 Small or concentrated contributor base Maturity64 Established project with proven stability Bus Factor1 Top contributor holds 93% 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 ~201 days Recently: every ~546 days Total 12 Last Release 197d ago PHP version history (3 changes)v0.2.0PHP ^7.1 v0.3.0PHP ^7.2 v0.7.0PHP >=8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/cb0e185b75648fb1c0095795e222f210700b86ae8c575c3cd6dd28a970ae2f34?d=identicon)[seregazhuk](/maintainers/seregazhuk) --- Top Contributors [![seregazhuk](https://avatars.githubusercontent.com/u/9959761?v=4)](https://github.com/seregazhuk "seregazhuk (160 commits)")[![gorbunov](https://avatars.githubusercontent.com/u/198664?v=4)](https://github.com/gorbunov "gorbunov (9 commits)")[![kpicaza](https://avatars.githubusercontent.com/u/1093654?v=4)](https://github.com/kpicaza "kpicaza (2 commits)")[![mmoreram](https://avatars.githubusercontent.com/u/521409?v=4)](https://github.com/mmoreram "mmoreram (1 commits)") --- Tags asyncasynchronouscliphpphp-watcherreactphpwatchphpasynchronouscliconsoleclockshellwatcherscriptsbashphp-watcher ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/seregazhuk-php-watcher/health.svg) ``` [![Health](https://phpackages.com/badges/seregazhuk-php-watcher/health.svg)](https://phpackages.com/packages/seregazhuk-php-watcher) ``` ### Alternatives [alecrabbit/php-console-spinner Extremely flexible spinner for \[async\] php cli applications 24032.0k2](/packages/alecrabbit-php-console-spinner)[nunomaduro/termwind It's like Tailwind CSS, but for the console. 2.5k239.8M285](/packages/nunomaduro-termwind)[acquia/orca A tool for testing a company's software packages together in the context of a realistic, functioning, best practices Drupal build 32902.4k](/packages/acquia-orca) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)