Cronjob on wt-modules

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Creating a job

Control panel → Cron Job Scheduler → New Job:

Field	Meaning
Name (slug)	technical identifier, `a-z 0-9 _ -`. Read-only for module-offered jobs (their `<module>:<name>` key is fixed); editable for jobs you create yourself.
Title	human readable name
Triggers	one or more time triggers (cron schedules) and/or event triggers — the job fires when any trigger fires. At least one is required.
Cron expression	(time trigger) standard 5-field cron or a macro (`@daily`, `@weekly`, …). Times are UTC.
Event name	(event trigger) the event this job reacts to. Slug or `<domain>:slug`, max 64 chars.
Command	a `modules_v4/<module>/cli/<script>.php` path or an allowlisted core command.
Arguments	plain options/values only (e.g. `--limit=5000`), max 10 tokens
Timeout	30 - 3600 s
Notify on failure	opt-in: alert the administrator accounts when this job fails

Available event names and commands are provided as datalists to make data entry easier.

The Tick

Mon, 01 Jan 0001 00:00:00 +0000

The tick is the heart of the module: once a minute it looks at every enabled job, decides what is due, and runs it. Neither the webtrees core nor the operating system does any scheduling itself — they only start tick.php .

flowchart TD
 subgraph Triggers["`⏱ Triggers *(once per minute)*`"]
 CRON["`🕑 OS cron / systemd<br/>*every minute*`"]
 WATCH["`👁 watch daemon<br/>*(in-module)*`"]
 end

 subgraph Guard["🛡 Guard"]
 TP["`📄 cli/tick.php · **cron:tick**<br/>*guard(): 403 over HTTP*`"]
 OFF{"`⚠ site offline?<br/>*data/offline.txt*`"}
 BOOT["`🚀 boot()<br/>*webtrees + DB*`"]
 end

 subgraph Selection["🔎 Select work"]
 TIME["`📅 time-based jobs<br/>**next_run_at due** *(UTC)*`"]
 CE[("`📦 cj_event<br/>*event queue*`")]
 DRAIN["`🧮 drain queue<br/>*coalesced · 60 s budget*`"]
 end

 subgraph Execution["`⚙ Execution *(isolated child)*`"]
 RUN["`🧪 JobRunner<br/>**proc_open**`"]
 LIM["`⏲ timeout 30–3600 s<br/>last **64 KB** · exit code`"]
 end

 subgraph Storage["💾 Storage"]
 CJRUN[("`cj_run<br/>*run history*`")]
 MARK["`🏷 tick.last<br/>*stale > 300 s → tick_stale*`"]
 end

 CRON --> Guard
 WATCH --> Guard
 TP --> OFF
 OFF -->|"offline"| SKIP["⏭ skip tick"]
 OFF -->|"online"| BOOT
 BOOT --> TIME
 BOOT --> DRAIN
 CE --> DRAIN
 TIME --> Execution
 DRAIN --> Execution
 RUN --> LIM
 LIM --> CJRUN
 BOOT --> MARK

 classDef sourceStyle fill:#e3f2fd,stroke:#1565C0,stroke-width:2px
 classDef queueStyle fill:#fff3e0,stroke:#E65100,stroke-width:2px
 classDef tickStyle fill:#e8f5e9,stroke:#2E7D32,stroke-width:2px
 classDef execStyle fill:#fce4ec,stroke:#C2185B,stroke-width:2px
 classDef storageStyle fill:#f5f5f5,stroke:#616161,stroke-width:1px

 class CRON,WATCH sourceStyle
 class OFF,CE queueStyle
 class TP,TIME,DRAIN tickStyle
 class RUN,LIM execStyle
 class CJRUN,MARK,SKIP storageStyle

What starts a tick

Pick one trigger (once):

CLI Scripts

Mon, 01 Jan 0001 00:00:00 +0000

Scripts

php modules_v4/cronjob/cli/tick.php # run all due jobs
php modules_v4/cronjob/cli/tick.php --dry-run # show what would run
php modules_v4/cronjob/cli/tick.php --job=<name> # run one specific job now
php modules_v4/cronjob/cli/tick.php --strict # exit 1 if any job failed
php modules_v4/cronjob/cli/tick.php --full-output # echo full job output (debugging!)
php modules_v4/cronjob/cli/watch.php # run the resident watch daemon

Exit codes: 0 = tick ran (job failures are recorded in the DB), 1 = environment problem or (with --strict) at least one job failed.

Security

Mon, 01 Jan 0001 00:00:00 +0000

No shell, ever. Commands are executed via proc_open with an argv array.
Command whitelist. Module scripts must match modules_v4/<module>/cli/<script>.php, exist, and resolve inside a modules_v4/<module>/cli/ directory. Core commands are limited to the read-only/export allowlist.
Argument validation. Every argument token must be a plain option or value — no shell metacharacters, no spaces inside tokens, max 10 tokens.
Working directories. Module scripts run from the webtrees root; core commands run from data/.
No sensitive data in stdout. The tick echoes summary lines only; full output stays in the admin-only run history.
UI actions are all named *Admin* (admin-only, CSRF-protected).
Kill switch: disable the module — the tick then does nothing.
The tick is single-instance (flock), and a job’s child process is hard-killed after its timeout (SIGKILL).
Event-queue coalescing. A flood of identical events cannot amplify into one job run per queued row.
Webhook token header-only. Send the token exclusively in the X-Cronjob-Token header.