README

Cadence creates and manages PHP daemons with ease for running all heavy-lifting tasks in the background.

Running cron jobs and background tasks in PHP typically requires system-level configuration, custom process management, or framework-specific solutions. Cadence eliminates this complexity. It turns any existing code into a managed daemon without modifications. It handles the repetitive execution cycle, memory management, graceful restarts, and structured logging so you can focus on your application logic. Enables real-time debugging by streaming output directly to your terminal or log files. Works standalone for development or pairs with Supervisor for production deployments.

Features

Use with Supervisor for robust process management in production environments
Run on foreground for development and debugging purposes
Run Cron jobs as daemons without modifying existing code
Start and stop daemons with ease
Monitor process status
Handle process logs
Easy integration with existing PHP applications
Framework agnostic, works with any PHP framework or plain PHP scripts

Click to play Demo Video ⬇️

Installation

Install Cadence via Composer. It's recommanded to install Cadence as a global dependency. Run the following command in terminal:

composer global require codesvault/cadence

Make sure Composer's global bin directory is in your system's PATH:

export PATH="$PATH:$HOME/.composer/vendor/bin"

Then run the following command to verify the installation:

cadence --help

It's recommended to use Cadence as a global dependency for easier access to the cadence command from any location in your terminal. Alternatively, you can install Cadence as a project dependency:

composer require codesvault/cadence

Usages for Development and Debugging

Developers can run Cadence on the foreground for development and real-time debugging purposes. This allows to run background-process and see real-time output and logs directly in your terminal or in log file.

Basic Usage

cadence </absolute/path/to/index.php> [options]

# Or

cadence <CLI Command> [options]

Examples

cadence /var/www/html/wp-cron.php

cadence /var/www/html/wp-cron.php --interval 10 --max-memory 256M

cadence '/var/www/html/artisan schedule:run' --env /var/www/.env

# with cli command
cadence 'curl -s https://example.com/webhook' -i 60
cadence 'echo hello' -n 5

Options

Short	Long	Type	Description
`-i`	`--interval`	INT	Sleep interval between runs [default: 60]
`-m`	`--max-memory`	STRING	Maximum memory usage before restart (e.g., 128M, 1G) [default: 128M]
`-t`	`--max-runtime`	INT	Maximum runtime in seconds before restart [default: 3600]
`-n`	`--max-cycles`	INT	Maximum number of cycles before restart [default: unlimited]
`-lf`	`--log-file`	STRING	Path to log file [default: none]
`-ll`	`--log-level`	STRING	Logging level (debug, info, warning, error) [default: info]
`-e`	`--env`	STRING	Path to .env file for configuration [default: auto-detect]
`-V`	`--version`	-	Display the version information
`-v`	`--verbose`	-	Enable verbose output
`-q`	`--quiet`	-	Suppress all output except errors
`-c`	`--config`	-	Show current configurations
`-h`	`--help`	-	Display this help message

Environment Configuration

Cadence can automatically detect and load environment variables from a .env file located in the same directory as your script. For example, if your script is located at /var/www/html/wp-cron.php, Cadence will look for a .env file at /var/www/html/.env.

You can also specify a custom path to the .env file using the --env option. The following environment variables can be used to configure Cadence:

Variable	Description	Default
`CAD_INTERVAL`	Interval between Cycles in seconds	60
`CAD_MAX_MEMORY`	Maximum memory usage before restart (e.g., 128M, 1G)	128M
`CAD_MAX_RUNTIME`	Maximum runtime in seconds before restart	3600
`CAD_MAX_CYCLES`	Maximum number of cycles before restart	unlimited
`CAD_LOG_FILE`	Path to log file	none
`CAD_LOG_LEVEL`	Logging level (debug, info, warning, error)	info
`CAD_DEBUG_LOG_FILE`	Path to debug log file	none

Production Usage with Supervisor

In production environments, it's recommended to use Cadence in conjunction with Supervisor.

Supervisor Installation & Configuration

Supervisor is a process control system that allows you to monitor and control long-running background processes. Install Supervisor on your Linux server:

sudo apt-get install supervisor

Create a Supervisor configuration file for Cadence process. For example, create a file named cadence.conf in /etc/supervisor/conf.d/ with the following configuration:

[program:cadence]
command=cadence /var/www/html/wp-cron.php
directory=/var/www/html
autostart=true
autorestart=true
stderr_logfile=/var/log/cadence_wp_cron.err.log
stdout_logfile=/var/log/cadence_wp_cron.out.log
user=www-data

Now make a .env file in /var/www/html/ directory for environment variables if needed. Cadence will automatically load the environment variables from this file.

CAD_LOG_FILE=/var/www/html/cad.log
CAD_LOG_LEVEL=debug
CAD_DEBUG_LOG_FILE=/var/www/html/cad_debug.log
CAD_INTERVAL=5
CAD_MAX_CYCLES=6
CAD_MAX_MEMORY=128M

Managing Cadence with Supervisor

You can manage the Cadence process using Supervisor commands:

# Start the Cadence process
sudo supervisorctl start cadence
# Stop the Cadence process
sudo supervisorctl stop cadence
# Restart the Cadence process
sudo supervisorctl restart cadence
# Check the status of the Cadence process
sudo supervisorctl status cadence

Contribution Guidelines

We welcome contributions to Cadence! Whether it's a bug fix, new feature, or documentation improvement, your help is appreciated. Please follow our contributing guidelines to get started.

codesvault / cadence

Maintainers

Details