jamesmorrison/php-wp-cron repository overview

⁠WordPress Cron Docker Images

Dedicated WordPress cron runner extending jamesmorrison/php. Runs due WordPress cron events through WP-CLI on a repeating interval, independently of web requests.

Image: jamesmorrison/php-wp-cron

⁠Versions and platforms

PHP versions: 8.2, 8.3, 8.4 and 8.5.

Platforms: linux/amd64 and linux/arm64.

Version tags follow the format jamesmorrison/php-wp-cron:<version>. Test tags use <version>-test-<commit-sha>.

Each version builds on the matching jamesmorrison/php:<version> image.

⁠Runtime defaults

PHP-FPM is installed in the base image but is not started by this image. The cron runner does not provide an HTTP or FastCGI service.

⁠Cron execution

The runner executes wp cron event run --due-now immediately after startup validation, then sleeps before the next run.

Only events that are due are executed. Events run sequentially within each invocation; the delay begins after the command finishes, so the interval between starts includes execution time.

WP-CLI output and timestamped success or warning messages are written to the container logs.

If a cron invocation fails, the runner logs a warning and continues with the next iteration. Invalid startup paths or missing WordPress files cause the container to exit.

⁠Environment variables

WP_CRON_FREQUENCY must be a valid duration accepted by sleep. An invalid value causes the runner to exit.

⁠WordPress requirements

The image does not install WordPress. It requires an existing installation with:

• wp-load.php inside WP_ROOT_DIR.
• wp-config.php inside WP_ROOT_DIR or its parent directory.
• Access to the site's database and any services required by cron callbacks.
• File permissions suitable for www-data, including write access where callbacks require it.

The runner should use the same WordPress files, configuration and database as the web application.

When this runner is responsible for scheduling, set DISABLE_WP_CRON to true in WordPress configuration to disable request-triggered cron. This is a WordPress constant, not an environment variable interpreted by the runner.

Avoid overlapping runners for the same site unless coordination is handled separately; the entrypoint does not implement a cross-container lock.

⁠Inherited PHP runtime

PHP extensions, WP-CLI, Composer and other tools are inherited from the PHP image⁠.

CLI OPcache is disabled by default. Each cron invocation starts a new PHP CLI process.

This image replaces the PHP base image's startup script. It does not perform the base script's mail, FPM session or opt-in Datadog configuration.

⁠Build arguments

PHP settings are inherited from the selected base image.

⁠Health check

Runs wp cron event list from WP_ROOT_DIR and checks its exit status.

The check verifies that WP-CLI can load WordPress and list cron events. It does not verify that the runner is advancing or that cron callbacks have completed successfully.