Monitor for any changes in your php application and automatically restart it (suitable for async apps).

Last update: Jun 22, 2022

PHP-watcher

PHP Version Build Status Total Downloads

Latest Stable Version Latest Version Latest Unstable Version

License

watcher logo

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

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

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

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

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 <file> 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

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

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

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

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

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

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

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

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

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

MIT http://rem.mit-license.org

How can I thank you?

Why not star this GitHub repo? I'd love the attention! Or, you can donate to my project on PayPal:

Support me with some coffee

Thanks!

GitHub

https://github.com/seregazhuk/php-watcher
Comments
  • 1. Option to prevent running process being wrapped into sh call

    I run into small problem while trying to run watcher on daemonized app, that processes posix signals, including SIGTERM, which is used to restart process. Since process wrapped into sh call, it was unable to correctly shutdown, release tcp port, which lead to defunct sh process on restart (since new process was unable to bind socket) and internally process kept watching that defunct sh process with wrong pid. I was able to track down this behavior into reactphp/childprocess (and it's documented feature), and added new command-line option to avoid this: --unwrap

    Not sure if it's a feature you want to add, tho.)

    Reviewed by gorbunov at 2019-10-10 13:50
  • 2. Make it compatible with Symfony 5

    Some required libraries are blocked to Symfony^4, blocking then all project requiring this watcher. We could make some push to them by adding some PRs, or just checking how to uncouple from them.

    Reviewed by mmoreram at 2019-11-29 16:56
  • 3. Implement custom spinner

    We need to decouple from alecrabbit/php-console-spinner. It has a lot of dependencies, for example under the hood it requires laravel container 6.0 and thus cannot be installed on the latest laravel version.

    The logic to render a spinner is pretty simple and can be easily implemented right here inside the library.

    Reviewed by seregazhuk at 2019-10-10 09:29
  • 4. Add php8 support in composer

    Helo @seregazhuk thanks for your excellent work.

    I've tried to update PHPUnit and Psalm too, but both require a config change, I think it should be better to update in different PRs;- D.

    Reviewed by kpicaza at 2021-01-24 13:37
  • 5. Compatibility with Symfony5

    Bug Report

    [email protected]:/app/symfony/app# php composer.phar require seregazhuk/php-watcher --dev
    Cannot load Xdebug - it was already loaded
    Using version ^0.5.2 for seregazhuk/php-watcher
    ./composer.json has been updated
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
    Restricting packages listed in "symfony/symfony" to "5.0.*"
    Your requirements could not be resolved to an installable set of packages.
    
      Problem 1
        - yosymfony/resource-watcher v2.0.0 requires symfony/finder ^2.7|^3.0|^4.0 -> no matching package found.
        - seregazhuk/php-watcher v0.5.2 requires yosymfony/resource-watcher ^2.0 -> satisfiable by yosymfony/resource-watcher[v2.0.0].
        - Installation request for seregazhuk/php-watcher ^0.5.2 -> satisfiable by seregazhuk/php-watcher[v0.5.2].
    
    Potential causes:
     - A typo in the package name
     - The package is not available in a stable-enough version according to your minimum-stability setting
       see <https://getcomposer.org/doc/04-schema.md#minimum-stability> for more details.
     - It's a private package and you forgot to add a custom repository to find it
    
    

    Input Code

    require seregazhuk/php-watcher --dev
    

    Expected behavior

    install the library

    Possible Solution

    get rid of yosymfony/resource-watcher dependency

    Reviewed by sergey-telpuk at 2019-12-11 13:22
  • 6. Improve spinner output

    Work directly with a cursor instead of using "\r". When reloading a script we should hide the spinner, otherwise part of it stays in the terminal.

    Reviewed by seregazhuk at 2019-10-17 14:21
  • 7. [BUG] Send termination signal to the process

    If the underlying script listens to POSIX signals, for example, to correctly shutdown (release tcp ports and etc) we need to explicitly send SIGTERM when restarting. Relates to #21

    Reviewed by seregazhuk at 2019-10-10 19:58
  • 8. Increase dependency options

    • Improves test document

      • PHP7.4
      • Lowest dependencies
      • Highest dependencies
    • Finder is required by some other libraries, and in lowest version of dependencies, the library goes to 2.7. We have forced the library to have a minimum dependency of ^4.3

    Reviewed by mmoreram at 2019-12-05 13:26
  • 9. Config building refactoring

    Separate into two steps: file-config and command line arguments. In order to be able to build a configuration in another console command with its own options.

    Reviewed by seregazhuk at 2019-11-18 20:02
  • 10. High CPU usage

    It works, it does its job, it's not based on node so I can stick to PHP when developing with PHP.

    However, it seems to have a quite significant CPU (I/O?) usage.

    Is there something that could be done to reduce that?

    Reviewed by xosofox at 2022-06-16 09:24
  • 11. Laravel Octane appears to be restarted twice

    Hi, thanks for this project 👋

    I am trying to use this project as a lightweight alternative to chokidar for restarting Laravel Octane: https://laravel.com/docs/8.x/octane#watching-for-file-changes

    When updating a watched file, it appears the process is restarted twice:

    [email protected]:~$ vendor/bin/php-watcher artisan --arguments=octane:start --watch=app
    
    [PHP-Watcher] 0.5.2
    [PHP-Watcher] watching: app
    [PHP-Watcher] starting `php artisan octane:start`
    ⠛
       INFO  Server running…
    
      Local: http://127.0.0.1:8000
    
      Press Ctrl+C to stop the server
    
    
    [PHP-Watcher] restarting due to changes...
    [PHP-Watcher] starting `php artisan octane:start`
    [PHP-Watcher] starting `php artisan octane:start`
    
    In Process.php line 170:
                                  
      Process is already running  
                                  
    
    watch [-w|--watch [WATCH]] [-e|--ext [EXT]] [-i|--ignore [IGNORE]] [--exec [EXEC]] [--delay [DELAY]] [--signal [SIGNAL]] [--arguments [ARGUMENTS]] [--config [CONFIG]] [--no-spinner] [--] <script>
    

    If you need to reproduce this locally, a plain Laravel install with Octane should do:

    • https://laravel.com/docs/8.x/installation
    • https://laravel.com/docs/8.x/octane#installation
    Reviewed by spawnia at 2021-09-08 17:07
  • 12. php-watcher has unmet requirements

    I'm trying to install php-watcher within latest composer docker with composer require seregazhuk/php-watcher command, but getting error:

    Package seregazhuk/php-watcher has a PHP requirement incompatible with your PHP version, PHP extensions and Composer version

    Docker container has Composer version 2.0.11 2021-02-24 14:57:23 and PHP 8.0.3 (cli) (built: Mar 6 2021 03:28:33) ( NTS ).

    I'm new to PHP and not sure what composer require --ignore-platform-reqs seregazhuk/php-watcher is doing, but after that ./vendor/bin/php-watcher app.php gives:

    Fatal error: Uncaught Error: Undefined constant "seregazhuk\PhpWatcher\Config\SIGINT" in /app/vendor/seregazhuk/php-watcher/src/Config/Config.php:40
    Stack trace:
    #0 /app/vendor/seregazhuk/php-watcher/src/Config/Builder.php(21): seregazhuk\PhpWatcher\Config\Config::fromArray(Array)
    #1 /app/vendor/seregazhuk/php-watcher/src/WatcherCommand.php(73): seregazhuk\PhpWatcher\Config\Builder->fromConfigFile('')
    #2 /app/vendor/seregazhuk/php-watcher/src/WatcherCommand.php(42): seregazhuk\PhpWatcher\WatcherCommand->buildConfig(Object(Symfony\Component\Console\Input\ArgvInput))
    #3 /app/vendor/symfony/console/Command/Command.php(256): seregazhuk\PhpWatcher\WatcherCommand->execute(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
    #4 /app/vendor/symfony/console/Application.php(971): Symfony\Component\Console\Command\Command->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
    #5 /app/vendor/symfony/console/Application.php(290): Symfony\Component\Console\Application->doRunCommand(Object(seregazhuk\PhpWatcher\WatcherCommand), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
    #6 /app/vendor/symfony/console/Application.php(166): Symfony\Component\Console\Application->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
    #7 /app/vendor/seregazhuk/php-watcher/php-watcher(18): Symfony\Component\Console\Application->run()

    And now composer check-platform-reqs outputs:

    Checking platform requirements for packages in the vendor dir
    ext-curl      8.0.3                                                 success  
    ext-json      8.0.3                                                 success  
    ext-mbstring  8.0.3                                                 success  
    ext-pcntl     n/a    seregazhuk/php-watcher requires ext-pcntl (*)  missing  
    php           8.0.3  seregazhuk/php-watcher requires php (^7.2)     failed   
    

    Is there a way I could use php-watcher in such setup?

    Reviewed by SlausB at 2021-03-16 22:47
A package that allows you to generate simple and fast Docker configurations for your Laravel application!

A package that allows you to generate simple and fast Docker configurations for your Laravel application!

Dec 23, 2021
Server automation framework and application

Puppet Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs administrative tasks (such as adding users, inst

Jun 30, 2022
Brew PHP switcher is a simple shell script to switch your apache and CLI quickly between major versions of PHP
Brew PHP switcher is a simple shell script to switch your apache and CLI quickly between major versions of PHP

Brew PHP switcher is a simple shell script to switch your apache and CLI quickly between major versions of PHP. If you support multiple products/projects that are built using either brand new or old legacy PHP functionality. For users of Homebrew (or brew for short) currently only.

Jun 26, 2022
A development tool for all your projects that is fast, easy, powerful and liberating
A development tool for all your projects that is fast, easy, powerful and liberating

Lando A Liberating Dev Tool For All Your Projects The local development and DevOps tool trusted by professional developers across the galaxy. Free you

Jun 25, 2022
🎲Neard is a portable WAMP software stack involving useful binaries, tools and applications for your web development.
🎲Neard is a portable WAMP software stack involving useful binaries, tools and applications for your web development.

About Neard is a portable WAMP software stack involving useful binaries, tools and applications for your web development. It also offers several versi

Jun 22, 2022
Demo of how you can run your Laravel app with Docker Compose. Look at docker-compose.yml and the docker folder. The rest is just a clean Laravel + Horizon install.

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

Oct 22, 2021
Quickly deploy a seedbox with self-hosted services and a web portal using Docker and docker-compose.
Quickly deploy a seedbox with self-hosted services and a web portal using Docker and docker-compose.

Seedbox Quickly deploy and configure a seedbox with self-hosted services and a web portal using Docker and a single docker-compose.yml file. Screensho

Jun 6, 2022
Laravel 5 with Dockerized Gulp, PHP-FPM, MySQL and nginx using docker-compose

docker-laravel Laravel 5 with Dockerized PHP-FPM, MySQL and nginx using docker-compose Usage Get Composer docker-compose run --rm phpnginx curl -O htt

Feb 8, 2022
Docker with PHP 7.4 fpm, Nginx, Composer, PhpUnit and MaridaDB

Clean Docker with PHP Docker with PHP 7.4 fpm, Nginx, Composer, PhpUnit and MariaDB Starting app docker-compose up -d Main page

Apr 26, 2022
ServD - a Docker PHP development environment heavily inspired by Laravel Valet and Laradock

ServD ServD is a Docker PHP development environment heavily inspired by Laravel Valet and Laradock, it supports multiple projects within a working dir

May 13, 2022
Vagrant is a tool for building and distributing development environments.

Vagrant Website: https://www.vagrantup.com/ Source: https://github.com/hashicorp/vagrant HashiCorp Discuss: https://discuss.hashicorp.com/c/vagrant/24

Jun 30, 2022
A modern Docker LAMP stack and MEAN stack for local development
A modern Docker LAMP stack and MEAN stack for local development

The Devilbox Usage | Architecture | Community | Features | Intranet | Screenshots | Contributing | Logos | License Support for valid https out of the

Jun 26, 2022
Up and running with small Docker environments
Up and running with small Docker environments

Vessel Up and running with small Docker dev environments. Documentation Full documentation can be found at https://vessel.shippingdocker.com. Install

Jun 29, 2022
Oxygen Builder's better workflow and environment

Oxygen Builder's better workflow and environment Built with ❤️ Official Website | Documentation | Change Log Supporting Artifact is an open source pro

Jun 9, 2022
Vagrant-boxes - Setup scripts and docs for my vagrant boxes, primarily aimed at Web/SilverStripe developement

zauberfisch's vagrant boxes zauberfisch/silverstripe-debian64 Debian 10 x86_64 LAMP Box with many extra features, pre-configured for SilverStripe Sour

Jan 24, 2020
This is a dockerized environment for testing and developing things on the fatfree-core.
This is a dockerized environment for testing and developing things on the fatfree-core.

F3 development bench This is a dockerized environment for testing and developing things on the fatfree-core. It uses Docker to spin up multiple contai

Mar 29, 2022
Phansible - generate Vagrant + Ansible dev environments for PHP

Phansible Phansible is a simple generator for Vagrant projects, targeting PHP development environments, using Ansible as Provisioner. It was inspired

Jun 29, 2022
Full PHP development environment for Docker.
Full PHP development environment for Docker.

Full PHP development environment based on Docker. Use Docker First - Learn About It Later! Join Us Awesome People Laradock is an MIT-licensed open sou

Jun 24, 2022