{"id":13828148,"url":"https://github.com/seregazhuk/php-watcher","last_synced_at":"2025-05-16T14:04:31.384Z","repository":{"id":41117481,"uuid":"210414855","full_name":"seregazhuk/php-watcher","owner":"seregazhuk","description":"Monitor for any changes in your php application and automatically restart it (suitable for async apps).","archived":false,"fork":false,"pushed_at":"2021-12-27T22:34:14.000Z","size":1035,"stargazers_count":392,"open_issues_count":7,"forks_count":32,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-12T10:58:20.435Z","etag":null,"topics":["async","asynchronous","cli","php","php-watcher","reactphp","watch"],"latest_commit_sha":null,"homepage":"https://sergeyzhuk.me/2019/10/18/php-watcher/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seregazhuk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-23T17:34:59.000Z","updated_at":"2025-03-10T08:21:48.000Z","dependencies_parsed_at":"2022-09-01T09:22:21.417Z","dependency_job_id":null,"html_url":"https://github.com/seregazhuk/php-watcher","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seregazhuk","download_url":"https://codeload.github.com/seregazhuk/php-watcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253937721,"owners_count":21987398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asynchronous","cli","php","php-watcher","reactphp","watch"],"created_at":"2024-08-04T09:02:34.271Z","updated_at":"2025-05-16T14:04:31.359Z","avatar_url":"https://github.com/seregazhuk.png","language":"PHP","readme":"# PHP-watcher\n\n[![PHP Version](https://img.shields.io/packagist/php-v/seregazhuk/php-watcher.svg)](https://php.net/)\n[![Build Status](https://travis-ci.org/seregazhuk/php-watcher.svg?branch=master)](https://travis-ci.org/seregazhuk/php-watcher)\n[![Total Downloads](https://poser.pugx.org/seregazhuk/php-watcher/downloads)](https://packagist.org/packages/seregazhuk/php-watcher)\n\n[![Latest Stable Version](https://poser.pugx.org/seregazhuk/php-watcher/v/stable)](https://packagist.org/packages/seregazhuk/php-watcher)\n[![Latest Version](https://img.shields.io/packagist/v/seregazhuk/php-watcher.svg)](https://packagist.org/packages/seregazhuk/php-watcher)\n[![Latest Unstable Version](https://poser.pugx.org/seregazhuk/php-watcher/v/unstable)](https://packagist.org/packages/seregazhuk/php-watcher)\n\n[![License](https://poser.pugx.org/seregazhuk/php-watcher/license)](https://packagist.org/packages/seregazhuk/php-watcher)\n\n![watcher logo](images/watcher.gif)\n\n\nPHP-watcher helps develop long-running PHP applications by automatically\n restarting them when file changes in the directory are detected.\n \nHere's how it looks like:\n \n![watcher screenshot](images/demo.svg)\n\nPHP-watcher does not require any additional changes to your code or method of\n development. `php-watcher` is a replacement wrapper for `php`, to use PHP\n -watcher replace the word `php` in the command line when executing your script.\n\n**Table of contents**\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Config files](#config-files)\n* [Monitoring multiple directories](#monitoring-multiple-directories)\n* [Specifying extension watch list](#specifying-extension-watch-list)\n* [Ignoring files](#ignoring-files)\n* [Delaying restarting](#delaying-restarting)\n* [Default executable](#default-executable)\n* [Gracefully reloading down your script](#gracefully-reloading-down-your-script)\n* [Automatic restart](#automatic-restart)\n* [Spinner](#spinner)\n\n## Installation\n\nYou can install this package globally like this:\n\n```bash\ncomposer global require seregazhuk/php-watcher\n```\n\nAfter that phpunit-watcher watch can be run in any directory on your system.\n\nAlternatively, you can install the package locally as a dev dependency in your\n project:\n\n```bash\ncomposer require seregazhuk/php-watcher --dev\n```\nLocally installed you can run it with `vendor/bin/php-watcher`.\n\n## Usage\n\nAll 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.\n\nPHP-watcher wraps your application, so you can pass all the arguments you\n would normally pass to your app:\n\n```bash\nphp-watcher [your php app]\n```\n\nUsing PHP-Watcher is simple. If your application accepts a host and port as the\n arguments, I can start it using option `--arguments`:\n\n```bash\nphp-watcher server.php --arguments localhost --arguments 8080\n```\n\nAny output from this script is prefixed with `[php-watcher]`, otherwise all\n output from your application, errors included, will be echoed out as expected.\n\n## Config files\n\nPHP-Watcher supports customization of its behavior with config files. The\nfile for options may be named `.php-watcher.yml`, `php-watcher.yml` or `php-watcher.yml.dist`. \nThe tool will look for a file in the current working directory in that order. \nAn alternative local configuration file can be specified with the `--config\n \u003cfile\u003e` option.\n\nThe specificity is as follows, so that a command line argument will always override the config file settings:\n\n- command line arguments\n- local config\n\nA config file can take any of the command line arguments, for example:\n\n```yml\nwatch:\n  - src\n  - config\nextensions:\n  - php\n  - yml\nignore:\n  - tests\n```\n\n## Monitoring multiple directories\n\nBy default, PHP-Watcher monitors the current working directory. If you want to\n take control of that option, use the `--watch` option to add specific paths:\n\n```bash\nphp-watcher --watch src --watch config server.php\n```\n\nNow PHP-Watcher will only restart if there are changes in the `./src` or\n `./config\n` directories. By default traverses sub-directories, so there's no\n need to explicitly include them.\n\n## Specifying extension watch list\n\nBy default, PHP-Watcher looks for files with the `.php` extension. If you use\n the `--ext` option and monitor `app,yml` PHP-Watcher will monitor files with\n  the extension of `.php` and `.yml`:\n\n```bash\nphp-watcher server.php --ext=php,yml\n```\n\nNow PHP-Watcher will restart on any changes to files in the directory (or\n subdirectories) with the extensions `.php`, `.yml`.\n\n## Ignoring files\n\nBy default, PHP-Watcher will only restart when a `.php` file changes. In\n some cases you may want to ignore some specific files, directories or file\n  patterns, to prevent PHP-Watcher from prematurely restarting your application.\n\nThis can be done via the command line:\n\n```bash\nphp-watcher server.php --ignore public/ --ignore tests/\n```\n\nOr specific files can be ignored:\n\n```bash\nphp-watcher server.php --ignore src/config.php\n```\n\nPatterns can also be ignored (but be sure to quote the arguments):\n\n```bash\nphp-watcher server.php --ignore 'src/config/*.php'\n```\n\nNote that by default, PHP-Watcher ignores all *dot* and VCS files.\n\n## Delaying restarting\n\nIn some situations, you may want to wait until a number of files have changed\n. The timeout before checking for new file changes is 1 second. If you're\n uploading a number of files and it's taking some number of seconds, this could cause your app to \n restart multiple times unnecessarily.\n\nTo add an extra throttle, or delay restarting, use the `--delay` option:\n\n```bash\nphp-watcher server.php --delay 10 \n```\n\nFor more precision, use a float:\n\n```bash\nphp-watcher server.php --delay 2.5 \n```\n\n## Default executable\n\nBy default, PHP-Watcher uses `php` bin executable to run your scripts. If you\n want to provide your own executable use `--exec` option or `executable` param in config file. This is particularly useful if you're working with\n  several PHP versions.\n\n```yml\nexecutable: php\n```\n\nor using CLI:\n\n```bash\nphp-watcher server.php --exec php7\n```\n\n### Running non-php scripts\n\nPHP-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:\n\n```bash\nphp-watcher server.js --exec node --watch app --ext=js\n```\n\nThe command above uses NodeJS to start `server.js` and then listens to changes in `app` directory.\n\n## Gracefully reloading down your script\n\nIt is possible to have PHP-watcher send any signal that you specify to your\n application.\n\n```bash\nphp-watcher --signal SIGTERM server.php\n```\n\nYour application can handle the signal as follows:\n\n```php\ndeclare(ticks = 1);\n\npcntl_signal(SIGTERM, 'terminationHandler');\n\nfunction terminationHandler()\n{\n    // ...        \n}\n```\n\nBy default PHP-watcher sends `SIGINT` signal.\n\n## Automatic restart\n\nPHP-watcher was originally written to restart long-running processes such as web servers, but \nit also supports apps that cleanly exit. If your script exits cleanly, the watcher will continue \nto monitor the directory (or directories) and restart the script if there are any changes. If the\nscript crashes PHP-watcher will notify you about that.\n\n![app exit](images/exit.svg)\n\n## Spinner\n\nBy default the watcher outputs a nice spinner which indicates that the process is running\nand watching your files. But if your system doesn't support ansi coded the watcher\nwill try to detect it and disable the spinner. Or you can always disable the spinner\nmanually with option '--no-spinner':\n\n```bash\nphp-watcher server.php --no-spinner\n```\n\n# License\n\nMIT [http://rem.mit-license.org](http://rem.mit-license.org)\n\n## How can I thank you?\n\nWhy not star this GitHub repo? I'd love the attention!\nOr, you can donate to my project on PayPal:\n\n[![Support me with some coffee](https://img.shields.io/badge/donate-paypal-orange.svg)](https://www.paypal.me/seregazhuk)\n\nThanks! \n","funding_links":["https://www.paypal.me/seregazhuk"],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregazhuk%2Fphp-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseregazhuk%2Fphp-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregazhuk%2Fphp-watcher/lists"}