Fix silent failure in core install when loading WordPress files fails

[Copilot]

Fix Silent Core Install Failure (Error 255)

Problem: wp core install fails silently with exit code 255 when loading WordPress files fails (e.g., due to missing PHP extensions). The command stops after "Begin WordPress load" with no helpful error message, making it difficult for users to diagnose the issue.

Root Cause: The require_once ABSPATH . 'wp-admin/includes/upgrade.php' statement had no error handling, causing silent failures when:

• WordPress installation files are missing
• Files have incorrect permissions
• PHP extensions required by WordPress are missing
• Other fatal errors occur during file loading

Solution:
Created a centralized require_upgrade_file() helper method that provides comprehensive error handling:

1. File Existence Check: Verifies the upgrade.php file exists before attempting to load it
2. Readability Check: Ensures the file has proper permissions to be read
3. Fatal Error Handler: Registers a shutdown function to catch fatal errors during file loading (E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR)
4. Completion Flag: Uses a flag to prevent the shutdown handler from executing on unrelated errors after successful completion
5. Detailed Error Messages: Provides context-specific error messages that guide users to the root cause

Changes Made:

• Added private method require_upgrade_file() in Core_Command class
• Replaced all 4 instances of bare require_once ABSPATH . 'wp-admin/includes/upgrade.php' with calls to the new helper method
• Applied to: do_install(), multisite_convert_(), update(), and update_db() methods
• Added completion flag to prevent shutdown handler from executing after successful require_once
• Simplified error handling by directly calling WP_CLI::error() (always available in WP-CLI context)
• Focused error type detection on fatal errors only (removed E_COMPILE_WARNING)
• Added Behat tests to verify error handling works correctly:
  • Test for missing upgrade.php file
  • Test for unreadable upgrade.php file (permissions issue)
  • Test for fatal error from missing PHP extension (simulates missing mysqli extension by replacing upgrade.php with error-triggering code)

Benefits:

• Users now receive clear, actionable error messages instead of silent failures
• Easier to diagnose missing PHP extensions or corrupted WordPress installations
• Centralized error handling logic for better maintainability
• Shutdown handler only executes for fatal errors during require_once
• Minimal code changes (affecting only error handling paths)
• Comprehensive test coverage including the original bug report scenario

Checklist

• Add error handling to capture failures when loading upgrade.php in do_install() method
• Add similar error handling to multisite_convert_() method
• Add similar error handling to update() method
• Add similar error handling to update_db() method
• Refactor into a reusable helper method for better maintainability
• Add completion flag to prevent shutdown handler from executing after success
• Simplify error handling (WP_CLI::error is always available)
• Focus on fatal errors only (removed non-fatal E_COMPILE_WARNING)
• Add Behat tests to verify error handling including missing mysqli extension scenario
• Fix test to avoid PHP parse errors
• Address code review feedback
• Verify PHP syntax

Original prompt

---

This section details on the original issue you should resolve

<issue_title>core install fails silently (error code 255)</issue_title>
<issue_description>## Bug Report

• Yes, I reviewed the contribution guidelines.
• Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.

Describe the current, buggy behavior

wp core install fails silently; echo $? shows error code 255

Describe how other contributors can replicate this bug

• clone my repo and run it on CircleCI: https://github.com/simpixelated/wordpress-ci
• view my current failing build: https://circleci.com/gh/simpixelated/wordpress-ci/13#tests/containers/0

Here are the commands I'm running after installing wp-cli:

wp core download
wp config create --dbhost=127.0.0.1 --dbname=$WORDPRESS_DB_NAME --dbuser=$WORDPRESS_DB_USER --dbpass=$WORDPRESS_DB_PASSWORD
wp core install --url=localhost --title=test --admin_user=test --admin_password=test --admin_email=test@example.com

Describe what you would expect as the correct outcome

install succeeds or at least provides more debug info about why it fails

Let us know what environment you are running this on

CircleCI using their PHP and MySQL docker images

Here is the output from running core install again on the CircleCI box directly (via ssh) with all --skip options and --debug added. I tried specifying a path for download, config, and install, but it still fails at the same spot. I can see that the wp-config.php file exists at that path and it looks correct.

Debug (bootstrap): argv: /usr/local/bin/wp core install --url=localhost --title=test --admin_user=test --admin_password=test --admin_email=test@example.com --path=wordpress --debug --skip-themes --skip-plugins --allow-root --skip-email --skip-packages (0.079s)
Debug (bootstrap): ABSPATH defined: /home/circleci/project/wordpress/ (0.079s)
Debug (bootstrap): Set URL: localhost (0.079s)
Debug (bootstrap): Begin WordPress load (0.08s)
Debug (bootstrap): wp-config.php path: /home/circleci/project/wordpress/wp-config.php (0.08s)
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@schlessera</author><body>
I assume in the reporter's case, the issue is something similar to an extension missing. I agree that WP-CLI should do a better job here of letting the user know what is happening. Silently failing is never a good option.</body></comment_new>
</comments>

• Fixes core install fails silently (error code 255) #123

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[codecov]

Codecov Report

❌ Patch coverage is 40.00000% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Core_Command.php	40.00%	21 Missing ⚠️

📢 Thoughts on this report? Let us know!