Add early check for iconv/mbstring extensions to prevent fatal errors #6185

Copilot · 2026-01-07T17:17:48Z

Symfony's polyfill-mbstring requires ext-iconv but Symfony doesn't require polyfill-iconv. When both mbstring and iconv extensions are missing, WP-CLI encounters a fatal error during bootstrap.

Changes

php/boot-fs.php: Added extension check after PHP version check. Exits with clear error message if both extensions are missing.

if ( ! extension_loaded( 'mbstring' ) && ! extension_loaded( 'iconv' ) ) {
    echo "Error: WP-CLI requires the mbstring or iconv PHP extension to be installed.\n";
    echo "Both extensions are currently missing. Please install at least one of them.\n";
    echo "For more information, see: https://make.wordpress.org/cli/handbook/installing/\n";
    die( -1 );
}

tests/BootFsTest.php: Unit tests verify the check exists and at least one extension is available in test environments.
features/bootstrap.feature: Behat scenario tests the extension check logic.
tests/bootstrap.php: Load TestCase class from wp-cli-tests package for test compatibility.

Related Issues

Addresses issues raised in #4700 and #4682 regarding the Symfony polyfill dependency chain.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

example.com
- Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php '-d short_open_tag=Off' '-d error_reporting=E_ALL' '-n' '-l' './bundle/rmccue/requests/src/Transsh (dns block)
nosuchhost_asdf_asdf_asdf.com
- Triggering command: /usr/bin/php php vendor/bin/phpunit --color=always --bootstrap ./vendor/wp-cli/wp-cli-tests/tests/bootstrap.php '-d short_open_tag=Off' '-d error_reporting=E_ALL' '-n' '-l' './bundle/rmccue/requests/src/Transsh (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>Consider adding check for iconv and mbstring availability to avoid PHP fatal.</issue_title>
<issue_description>See #4700 and #4682

As noted by @schlessera #4682 (comment)

Related: symfony/polyfill#66

Symfony deliberately doesn't require the iconv polyfill even though the mbstring polyfill needs it, which is the worst of both worlds really, so consider adding a check if both iconv and mbstring not available and error if so, to avoid getting a PHP fatal.</issue_description>

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

Fixes Consider adding check for iconv and mbstring availability to avoid PHP fatal. #4704

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

codecov · 2026-01-07T18:11:33Z

Codecov Report

❌ Patch coverage is 0% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
php/boot-fs.php	0.00%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR adds an early check for mbstring/iconv extensions to prevent fatal errors during WP-CLI bootstrap. When Symfony's polyfill-mbstring requires ext-iconv but both extensions are missing, WP-CLI encounters a fatal error. The solution adds a validation check early in the bootstrap process to provide a clear error message instead.

Added extension check in php/boot-fs.php after PHP version check to exit gracefully with a helpful error message
Added unit tests to verify the extension check exists and at least one extension is available
Added Behat scenario to test the extension check behavior

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
php/boot-fs.php	Added early extension check for mbstring/iconv with clear error messaging
tests/BootFsTest.php	Unit tests to verify extension check exists and environment has required extensions
tests/bootstrap.php	Load TestCase class from wp-cli-tests package for test compatibility
features/bootstrap.feature	Behat scenario testing the extension check logic with mock file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-09T09:43:23Z

tests/BootFsTest.php

+	 * Test that the boot-fs.php file contains the extension check
+	 */
+	public function testExtensionCheckExists() {
+		$boot_fs_content = file_get_contents( WP_CLI_ROOT . '/php/boot-fs.php' );
+
+		// Ensure file was read successfully
+		$this->assertNotFalse( $boot_fs_content, 'Could not read boot-fs.php file' );
+
+		// Check that the file contains the extension check
+		$this->assertStringContainsString( 'extension_loaded', $boot_fs_content );
+		$this->assertStringContainsString( 'mbstring', $boot_fs_content );
+		$this->assertStringContainsString( 'iconv', $boot_fs_content );
+		$this->assertStringContainsString( 'WP-CLI requires the mbstring or iconv PHP extension', $boot_fs_content );
+	}
+
+	/**


The test testExtensionCheckExists() uses string matching to verify the extension check exists in the boot-fs.php file. This approach is fragile because it tests implementation details rather than behavior. If the code is refactored (e.g., strings are changed, variable names updated), the test could fail even if the functionality works correctly.

Consider testing the behavior instead by using a Behat scenario (which already exists) or by testing the actual exit behavior when extensions are missing. However, given that boot-fs.php is early bootstrap code that terminates the process, string matching may be a pragmatic approach in this specific case.

Suggested change

* Test that the boot-fs.php file contains the extension check

*/

public function testExtensionCheckExists() {

$boot_fs_content = file_get_contents( WP_CLI_ROOT . '/php/boot-fs.php' );

// Ensure file was read successfully

$this->assertNotFalse( $boot_fs_content, 'Could not read boot-fs.php file' );

// Check that the file contains the extension check

$this->assertStringContainsString( 'extension_loaded', $boot_fs_content );

$this->assertStringContainsString( 'mbstring', $boot_fs_content );

$this->assertStringContainsString( 'iconv', $boot_fs_content );

$this->assertStringContainsString( 'WP-CLI requires the mbstring or iconv PHP extension', $boot_fs_content );

}

/**

Harshad071 · 2026-01-11T12:00:01Z

This looks solid overall 👍
Regarding the Codecov patch failure: since this check runs during early bootstrap and exits immediately, it’s likely not reachable in coverage runs. That might explain the 0% patch coverage on boot-fs.php.

One option could be to exclude this block from coverage, or alternatively rely on the existing Behat scenario as sufficient behavioral coverage for this case. Curious what you think is the preferred approach here.

Initial plan

81530da

Copilot AI assigned Copilot and swissspidy Jan 7, 2026

Copilot started work on behalf of swissspidy January 7, 2026 17:18 View session

Copilot AI and others added 3 commits January 7, 2026 17:31

Add check for iconv and mbstring availability to avoid PHP fatal

8dbde6f

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Update BootFsTest to use WP_CLI\Tests\TestCase for consistency

f8a9972

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Fix PHPStan errors in BootFsTest

39a25cd

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add check for iconv and mbstring availability~~ Add early check for iconv/mbstring extensions to prevent fatal errors Jan 7, 2026

Copilot AI requested a review from swissspidy January 7, 2026 17:38

Copilot finished work on behalf of swissspidy January 7, 2026 17:38

swissspidy requested a review from Copilot January 9, 2026 09:40

Copilot started reviewing on behalf of swissspidy January 9, 2026 09:41 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add early check for iconv/mbstring extensions to prevent fatal errors #6185

Add early check for iconv/mbstring extensions to prevent fatal errors #6185

Copilot AI commented Jan 7, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 9, 2026

Uh oh!

Harshad071 commented Jan 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add early check for iconv/mbstring extensions to prevent fatal errors #6185

Are you sure you want to change the base?

Add early check for iconv/mbstring extensions to prevent fatal errors #6185

Conversation

Copilot AI commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Related Issues

I tried to connect to the following addresses, but was blocked by firewall rules:

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

Uh oh!

codecov bot commented Jan 7, 2026

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Harshad071 commented Jan 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jan 7, 2026 •

edited

Loading