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

Overview

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!

Comments
  • Option to prevent running process being wrapped into sh call

    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.)

    enhancement 
    opened by gorbunov 7
  • Make it compatible with Symfony 5

    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.

    enhancement 
    opened by mmoreram 3
  • Implement custom spinner

    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.

    enhancement 
    opened by seregazhuk 3
  • Add php8 support in composer

    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.

    opened by kpicaza 2
  • Compatibility with Symfony5

    Compatibility with Symfony5

    Bug Report

    root@1b51a4eb9dd9:/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

    opened by sergey-telpuk 1
  • Improve spinner output

    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.

    enhancement 
    opened by seregazhuk 1
  • [BUG] Send termination signal to the process

    [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

    opened by seregazhuk 1
  • Increase dependency options

    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

    opened by mmoreram 0
  • Config building refactoring

    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.

    opened by seregazhuk 0
  • High CPU usage

    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?

    opened by xosofox 0
  • Laravel Octane appears to be restarted twice

    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:

    www-data@nemo-api:~$ 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
    opened by spawnia 8
  • php-watcher has unmet requirements

    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?

    opened by SlausB 1
Releases(v0.5.2)
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!

Lucas Nepomuceno 3 Oct 8, 2022
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

Puppet 6.8k Dec 31, 2022
Finally a sane way to register available commands and arguments and match your command line in PHP

clue/commander Finally a sane way to register available commands and arguments and match your command line in PHP. You want to build a command line in

Christian Lück 172 Nov 27, 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. 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.

Phil Cook 872 Dec 22, 2022
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

Lando 3.6k Jan 7, 2023
🎲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

Neard 335 Dec 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

Matt 5 Oct 22, 2021
Dockerized PHP development stack: Nginx, MySQL, MongoDB, PHP-FPM, HHVM, Memcached, Redis, Elasticsearch and RabbitMQ

PHP Dockerized Dockerized PHP development stack: Nginx, MySQL, MongoDB, PHP-FPM, HHVM, Memcached, Redis, Elasticsearch and RabbitMQ PHP Dockerized giv

Kasper Isager Dalsgarð 1.1k Dec 30, 2022
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

null 6 Dec 7, 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

Harsh Vakharia 83 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

Grzegorz Bielski 7 Nov 17, 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

Matt Clinton 2 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

HashiCorp 24.8k Jan 2, 2023
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

cytopia 4k Jan 8, 2023
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

Shipping Docker 1.1k Dec 17, 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

AncientWorks 10 Dec 3, 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

null 6 Jan 24, 2020
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

Fat-Free Framework Factory 9 Sep 20, 2022