We love PHP for its simplicity: you write the code, refresh the page in the browser and immediately see the changes. But if it comes to console commands, which can be long-lived processes — for example, if we write an asynchronous HTTP server to upload files — development can be very painful.
There was no suitable solution in the PHP ecosystem to automatically restart applications when changes were made to the source code. So I decided to make my tool - in pure PHP and with access through Composer.
It's like Nodemon, but in PHP
For a while I myself used Nodemon . This is a tool from the world of Node.js, however if you tweak it a bit, you can use it with PHP scripts. But in fact, I don’t want to install Node.js and drag a bunch of NPM packages unknown to me into my asynchronous PHP application to restart it.
Since I actively chat on Twitter, I asked there who else had this problem and would like to get a solution. Seeing interest, I sat down to write a tool that provides the same functionality as Nodemon, only in PHP and for PHP .
A month has passed: with PHP-Watcher you no longer need to install Nodemon or any other NPM package to develop your long-lived PHP application.
That's how it works
The library can be installed through Composer:
composer global require seregazhuk/php-watcher
Imagine that we are working on a long-lived Symfony-based application. The entry point to our application is the public / index.php file. We want to track changes in the src and config folders. We also want the application to restart automatically as soon as we change the source code or configuration parameters. Here's how to solve this problem:
php-watcher public/index.php --watch src --watch config
The command will run the script public / index.php, which will begin to track changes in the src and config directories. As soon as the file changes in any of them, PHP-Watcher will restart the script.
By default, it only tracks changes to PHP files. But Symfony stores its configs in yaml. Therefore, we need to explicitly tell the watch so that it tracks both PHP and yaml files. This is done using the --ext option:
php-watcher public/index.php --watch src --watch config --ext php,yaml
Suppose we understand that we do not need to restart applications with any changes within the src directory. For example, we would like to ignore changes in the src / Migrations subdirectory. In this case, you can use the --ignore option:
php-watcher public/index.php --watch src --watch config --ext php,yaml --ignore Migrations
Now PHP-Watcher will start tracking changes in the src and config directories, but will ignore any changes inside the Migrations subdirectory. In addition, it by default ignores changes in all dot and VCS files.
Watcher supports customizing its behavior not only through command line options, but also through configuration files. If you do not want to pass a bunch of options and parameters every time on the command line, you can create a .php-watcher.yml configuration file. For example, the previous command can be replaced with the following configuration file:
watch: - src - config extensions: - php - yaml ignore: - Migrations
Having such a file, we can simply activate the "watch" by specifying only the PHP script that needs to be restarted. All other settings will be taken from the file:
php-watcher public/index.php
What happens if we have both a configuration file and command line arguments? In this case, all arguments passed from the command line will overwrite the corresponding values ​​from the configuration file.
By default, PHP-Watcher uses the PHP executable to run the script. We write the command in the terminal:
php-watcher public/index.php
Under the hood, a child process is created with the php command public / index.php. In most cases, this is what you need. However, if your environment has a different executable file, you can explicitly specify which command to execute. For example, when we have several versions of PHP on the same system, and we want to run our application with the php7.4 executable, you can use the --exec option and specify your executable:
php-watcher public/index.php --exec php7.4
The same thing through the configuration file:
watch: - src - config executable: php7.4
PHP-Watcher does not automatically restart the application if it crashes. In the dev environment, this is not particularly necessary - because while we are developing a new application, it is normal that sometimes it will crash. If the application crashes (terminated with a code other than 0), the "watch" will let us know about it. As soon as we fix the code, the changes will be detected in the sources - and the application will restart.
Thanks for attention! More information about PHP-Watcher can be found on the project’s homepage on GitHub . The documentation describes the basic patterns of use. The project is still under development, but the API is already quite stable. I will be glad if you use it.
PS Feel free to leave feedback and suggestions through issue on GitHub.