Skip to content

[codex] Expose branch preview PHP fatals#388

Merged
adamziel merged 1 commit into
trunkfrom
codex/branch-preview-fatal-logs
May 19, 2026
Merged

[codex] Expose branch preview PHP fatals#388
adamziel merged 1 commit into
trunkfrom
codex/branch-preview-fatal-logs

Conversation

@adamziel
Copy link
Copy Markdown
Contributor

What it does

Makes branch-preview PHP fatals visible in ForkPress logs instead of leaving users with only WordPress' generic critical-error screen.

The change:

  • disables WordPress' fatal-error recovery handler in generated COW/CAS branch configs
  • adds a COW router shutdown logger that records branch name, request URI, file, line, and fatal message to wp-debug.log
  • preserves that setting when Git pushes rewrite branch wp-config.php
  • documents that branch-preview fatals should now be visible through forkpress logs --file wp

Rationale

Remote clones can boot far enough for WordPress to load plugins/themes, then fatal inside a site-specific plugin. WordPress recovery mode masks that as "There has been a critical error on this website", and the current logs can lack the branch/request context needed to debug the cloned site.

Implementation

runtime/cow/router.php now registers a shutdown handler before requiring branch PHP. On fatal shutdown it writes a structured line to the ForkPress debug log and PHP error log. Generated configs define WP_DISABLE_FATAL_ERROR_HANDLER so PHP fatals flow to ForkPress logging instead of WordPress' generic recovery page. Git-side wp-config.php normalization inserts or normalizes the same constant when pushed configs are applied to materialized branches.

Testing instructions

Checked locally:

php -l runtime/cow/router.php
php -l runtime/cow/bootstrap_wp.php
php -l scripts/cow/git_server.php
php -l tests/cow/router_paths.php
php -l tests/cow/git_server.php
php tests/cow/router_paths.php
php tests/cow/git_server.php
FORKPRESS_RUNTIME_BUNDLE=/dev/null cargo test -p forkpress-cli remote_clone
cargo fmt --check
git diff --check

@adamziel adamziel marked this pull request as ready for review May 19, 2026 09:21
@adamziel adamziel merged commit 6557cce into trunk May 19, 2026
13 checks passed
@adamziel adamziel deleted the codex/branch-preview-fatal-logs branch May 19, 2026 09:21
@adamziel adamziel mentioned this pull request May 19, 2026
adamziel added a commit that referenced this pull request May 19, 2026
## Release `v0.1.49`

Version bump and release metadata update for `v0.1.49`.

**Changelog draft:**
* Update release workflows for Node 24 actions
([#384](#384))
* Improve remote clone SSH failures
([#387](#387))
* Expose branch preview PHP fatals
([#388](#388))
* Improve docs social preview
* Heal remote clone branch boot dependencies
([#389](#389))

**Full changelog:**
v0.1.48...release/v0.1.49

## Next steps

1. **Review** the changes in this pull request.
2. **Push** any additional edits to this branch (`release/v0.1.49`).
3. **Merge** this pull request to publish `v0.1.49`.

Merging will automatically build ForkPress binaries, create a GitHub
release, and update the Homebrew formula.

Co-authored-by: Codex <codex@openai.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants