Protect `env:start` command against connection issues

[desrosj]

[59231] moved the composer update command from the test:php script to env:start to prevent the command from running every time unit tests are run.

ticket:57189#comment:22 from @flixos90 mentions a situation where packagist.org was experiencing some down time and caused the env:start command to fail. The reason for this can be hard to decipher and it's easy to assume that you are experiencing a Docker issue.

Ideally the composer update command catches errors and displays a more informative notice to the user. "There was a failure running composer update." with some guidance to fix the issue.

See #57189.

[iamadisingh]

Currently, the composer update command is run as part of the env:start npm script in package.json

"env:start": "node ./tools/local-env/scripts/start.js && node ./tools/local-env/scripts/docker.js run -T --rm php composer update -W",

To provide a clearer, actionable error message, we could move the composer update logic into the JS startup script start.js. This would allow us to run Composer using Node's spawnSync, check the exit code, and print a custom message if it fails (something like "There was a failure running composer update. This is often caused by network issues or Packagist.org downtime. Please check your internet connection and try again.").

This PR improves the developer experience for npm run env:start by providing clear, actionable error messages if composer update fails.

Trac ticket: https://core.trac.wordpress.org/ticket/62807

[r1k0]

Combined Bug Reproduction & Patch Test Report

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/9360

Steps to Reproduce or Test

1. Inside the wordpress-develop directory.
2. Run the following commands:

   npm install
   npm run build:dev
   

3. Also run this sudo nano /etc/hosts and add this line at the end 127.0.0.1 packagist.org repo.packagist.org, save and exit. (This should simulate Packagist down).
4. Run npm run env:start
5. 🐞 Observe the output when the environment attempts to start.

Expected Results

When reproducing a bug:

• ❌ Error condition occurs.
• npm run env:start fails with raw Composer/Curl output (e.g. curl error 7) and no clear indication that the failure is due to Packagist/network issues.

When testing a patch to validate it works as expected:

• ✅ npm run env:start fails gracefully.`
• A clear, actionable error message is displayed indicating that composer update failed and that the issue is commonly caused by network problems or Packagist.org downtime.
• The message does not suggest a Docker failure.

Output before patch

> WordPress@7.0.0 env:start
> node ./tools/local-env/scripts/start.js && node ./tools/local-env/scripts/docker.js run -T --rm php composer update -W

[+] up 5/5
 ✔ Network wordpress-develop_wpdevnet              Created                                                                                 0.4s 
 ✔ Container wordpress-develop-php-1               Created                                                                                 3.1s 
 ✔ Container wordpress-develop-mysql-1             Healthy                                                                               196.7s 
 ✔ Container wordpress-develop-cli-1               Created                                                                                 2.4s 
 ✔ Container wordpress-develop-wordpress-develop-1 Created                                                                                 2.7s 
.env file already exists. .env.example was not copied.
Container wordpress-develop-php-run-032dd7814657 Creating 
Container wordpress-develop-php-run-032dd7814657 Created 
Loading composer repositories with package information

In CurlDownloader.php line 398:
                                                                               
  curl error 7 while downloading https://repo.packagist.org/packages.json: Fa  
  iled to connect to repo.packagist.org port 443: Connection refused           
                                                                                                          
                                                                               

update [--with WITH] [--prefer-source] [--prefer-dist] [--prefer-install PREFER-INSTALL] [--dry-run] [--dev] [--no-dev] [--lock] [--no-install] [--no-audit] [--audit-format AUDIT-FORMAT] [--no-security-blocking] [--no-autoloader] [--no-suggest] [--no-progress] [-w|--with-dependencies] [-W|--with-all-dependencies] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [-a|--classmap-authoritative] [--apcu-autoloader] [--apcu-autoloader-prefix APCU-AUTOLOADER-PREFIX] [--ignore-platform-req IGNORE-PLATFORM-REQ] [--ignore-platform-reqs] [--prefer-stable] [--prefer-lowest] [-m|--minimal-changes] [--patch-only] [-i|--interactive] [--root-reqs] [--bump-after-update [BUMP-AFTER-UPDATE]] [--] [<packages>...]

Environment

• OS: Linux
• WordPress: 7.0-alpha (wordpress-develop)
• Node.js: v20.19.6
• npm: 10.8.2
• Docker: v4.56.0

Actual Results

Without patch:

• ❌ env:start fails during the Composer step with Curl/Composer errors (e.g. “Connection refused”), making the root cause difficult to identify.

With patch applied:

• ✅ Issue resolved with patch.
• env:start fails when Packagist is unavailable.
• The failure is accompanied by a clear message:

"There was a failure running composer update."
“This is often caused by network issues or Packagist.org downtime.”
“Please check your internet connection and try again.”

Output after patch

> WordPress@7.0.0 env:start
> node ./tools/local-env/scripts/start.js

[+] up 5/5
 ✔ Network wordpress-develop_wpdevnet              Created                                                                                 0.6s 
 ✔ Container wordpress-develop-php-1               Created                                                                                 3.0s 
 ✔ Container wordpress-develop-mysql-1             Healthy                                                                                66.6s 
 ✔ Container wordpress-develop-wordpress-develop-1 Created                                                                                 3.4s 
 ✔ Container wordpress-develop-cli-1               Created                                                                                 3.1s 
Container wordpress-develop-php-run-d17f917b3495 Creating 
Container wordpress-develop-php-run-d17f917b3495 Created 
Loading composer repositories with package information

In CurlDownloader.php line 398:
                                                                               
  curl error 7 while downloading https://repo.packagist.org/packages.json: Fa  
  iled to connect to repo.packagist.org port 443: Connection refused           
                                                                               

update [--with WITH] [--prefer-source] [--prefer-dist] [--prefer-install PREFER-INSTALL] [--dry-run] [--dev] [--no-dev] [--lock] [--no-install] [--no-audit] [--audit-format AUDIT-FORMAT] [--no-security-blocking] [--no-autoloader] [--no-suggest] [--no-progress] [-w|--with-dependencies] [-W|--with-all-dependencies] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [-a|--classmap-authoritative] [--apcu-autoloader] [--apcu-autoloader-prefix APCU-AUTOLOADER-PREFIX] [--ignore-platform-req IGNORE-PLATFORM-REQ] [--ignore-platform-reqs] [--prefer-stable] [--prefer-lowest] [-m|--minimal-changes] [--patch-only] [-i|--interactive] [--root-reqs] [--bump-after-update [BUMP-AFTER-UPDATE]] [--] [<packages>...]



There was a failure running composer update.
This is often caused by network issues or Packagist.org downtime.
Please check your internet connection and try again.

Additional Notes

• Ensure to remove the line added in step 3 to make Packagist reachable.

Seems there's a left-over orphan Docker container when the Composer update fails. Maybe it can be removed at the end there?

[azaozz]

Replying to r1k0:

Thanks for the detailed test/bug report! Seems to work here too, just left couple of nitpick comments on the PR.

Seems there's a left-over orphan Docker container when the Composer update fails. Maybe it can be removed at the end there?

Thank you for the feedback! I've updated the PR to address both concerns

[azaozz]

LGTM