docs(roadmap): PHP preload/warmup plan (P3) — pre-implementation

[andypost]

Summary

Pre-implementation plan for roadmap item P3 — PHP preload/warmup hook (roadmap/unit-php.md:72-77). No code yet; this PR exists to review the design before cutting patches.

Adds roadmap/plan-php-preload-warmup.md covering:

• Preload: new "preload" config key mapped to opcache.preload via sapi_module_struct.ini_entries, injected between sapi_startup() and php_module_startup() in nxt_php_setup() so PHP actually reads it.
• Warmup: new "warmup": [...] array eagerly passed to opcache_compile_file() after targets resolve in nxt_php_start(), before the worker accepts requests. Soft failures only.
• Error policy: preload = PHP-native fatal (worker restart); warmup = log + continue.
• Extensive test matrix: validation negatives, happy paths, missing file, syntax error, opcache-disabled, targets interaction, reload, unicode/symlinks, 200-script stress, options.file conflict.
• Shared scaffolding with /run + scheduler (roadmap/plan-run.md): array-of-string validator, generation-bump reload path, control-API dispatcher pattern. On-demand /control/applications/<name>/warmup endpoint and port RPC deferred to P7 to keep P3 landable in ~3 days.

Critical files identified

• src/nxt_php_sapi.c (lines 313-487, 690-780, 1014-1045)
• src/nxt_application.h:62-65
• src/nxt_main_process.c:236-248
• src/nxt_conf_validation.c:1049, 3238, 3499-3518
• New: test/test_php_preload.py, test/test_php_warmup.py, test/php/preload/, test/php/warmup/

Test plan

• Review design choices, especially ini_entries injection timing and warmup relative-path semantics (resolves against first target's root).
• Confirm soft-failure policy for warmup (log + skip vs. fatal).
• Confirm deferring on-demand /warmup endpoint to P7 is acceptable.
• After approval: implement per §File-by-File and run the test matrix described in the plan.

Draft PR — will close or convert to ready once implementation lands in follow-up commits.

https://claude.ai/code/session_01FDhY6aDxweH1CJE8Ma5BfK

[gemini-code-assist]

Code Review

This pull request proposes an implementation plan for PHP preload and warmup hooks to eliminate cold-start spikes by pre-compiling scripts. The review feedback suggests optimizing the warmup loop's error handling to ensure robustness, warns about potential preloading failures when running as root, and recommends that Unit configuration settings override php.ini directives to maintain consistency.

[gemini-code-assist]

Note that PHP's opcache.preload will fail if the process is running as root and opcache.preload_user is not set to a non-root user. If conf->user defaults to root (e.g., if Unit is started as root and no user is configured for the app), preloading will fail. It might be worth adding a validation check or a warning if the resulting user is root.

[andypost]

Good catch — folded in d8b96a3. Plan now: opcache.preload_user defaults to conf->user, falls back to the worker's effective uid when conf->user is empty, and if the resolved user would be root (uid 0) we emit a loud WARN and skip the injection so the worker stays up rather than crashing at php_module_startup. Verified locally against PHP 8.4.19: bad preload paths produce PHP Fatal error: Failed opening required '…' at startup, which matches what our negative-case alert regex will key on.

---

Generated by Claude Code

[gemini-code-assist]

To ensure that a syntax error in one file doesn't prevent the rest of the list from being warmed up, the zend_try / zend_catch block should be placed inside the loop iterating over the warmup array. If placed outside the loop, any bailout triggered by opcache_compile_file will terminate the entire warmup process for that worker.

[andypost]

Agreed, real bug in the plan — fixed in d8b96a3. The zend_try { … } zend_catch { … } zend_end_try(); now wraps each loop iteration individually, not the outer loop. One bailout from opcache_compile_file skips only the failing entry and sibling entries continue to compile. Both the "High-Level Approach" prose and the src/nxt_php_sapi.c insertion-site description have been updated to make the per-iteration scoping explicit.

---

Generated by Claude Code

[gemini-code-assist]

There is a contradiction between the conflict policy here and the risk mitigation on line 236. This table states that options.file should win, but line 236 suggests logging an error if the active value doesn't match the Unit configuration. In standard PHP SAPI behavior, sapi_module_struct.ini_entries are processed after php.ini and thus act as overrides. It is recommended to let the Unit configuration key win, as this is more consistent with Unit's management of other application options and avoids the complexity of pre-parsing the INI file to detect conflicts.

Suggested change

	| `options.file` also sets `opcache.preload` | `options.file` wins for every directive; our `ini_entries` only fills in what the file left blank. Log INFO on conflict. |
	| `options.file` also sets `opcache.preload` | Unit configuration key wins (standard SAPI behavior); `ini_entries` overrides `options.file`. Log INFO on conflict. |

[andypost]

Accepted — flipped the policy in d8b96a3. You're right on both counts: PHP's SAPI parses ini_entries after php.ini, so our injection naturally overrides options.file; and this lines up with Unit's existing convention where config keys (user, group, working_directory) beat file-supplied values. Removes the need to pre-parse the user's ini to detect conflicts. Error Policy table row now reads "Unit preload key wins … INFO log on detected conflict." The "Reviewer Burden & Binary Compatibility" §Opt-in guarantees section was aligned to the same story.

---

Generated by Claude Code