Add more verbose debug output

[Copilot]

Implementation Plan: Add debug output for doctor check command

• Explore repository structure and understand the codebase
• Implement debug logging using WP_CLI::debug() with 'doctor' group
• Add debug output when checks are being executed
• Add debug output for file checks (which can be slow on large sites)
• Create Behat tests for the --debug=doctor flag
• Address code review feedback (extract magic number to constant)
• Run security checks
• Fix failing test (use cache-flush instead of php-in-upload)
• Address misleading file count wording (use "items visited" terminology)
• Final verification

Summary

Successfully implemented debug output for the wp doctor check command using WP-CLI's built-in --debug=doctor flag. This addresses the reported issue where large WordPress sites appeared to hang during checks by providing detailed visibility into check execution.

Key Features:

• Shows which check is currently running (when using --debug=doctor)
• Displays status after each check completes
• For file checks, shows scanning progress every 1000 items (using "items visited" terminology for accuracy)
• Debug output goes to STDERR, never corrupts machine-readable output formats
• Leverages existing WP-CLI infrastructure instead of custom flag implementation
• All changes are backward compatible (opt-in feature)

Usage:

wp doctor check --all --debug=doctor

Code Quality:

• ✅ Passes all static analysis checks (lint, phpcs, phpstan)
• ✅ Uses WP_CLI::debug() with 'doctor' group (consistent with existing codebase)
• ✅ Test coverage using --debug=doctor and checking STDERR
• ✅ Wording changed to "items visited" for accuracy (addresses that directories are also counted)
• ✅ No custom format checking needed (debug output automatically goes to STDERR)
• ✅ Follows existing codebase conventions

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Introduce --verbose flag to provide more visibility into what checks are doing</issue_title>
<issue_description>Run wp doctor check command as follows:
[root@server production]# wp doctor check --all --allow-root

Check begins but never gets past 12%

Running checks 12 % [====================> ] 0:16 / 2:15[root@server production]#

Expected behavior is that it completes or returns an error message.

Ideally a fix would complete the scan, alternatively provide a verbose error message.

Thanks!

PHP 8.0, WP 6.0.3, updated to latest production version of WP CLI and doctor package.
Large WP site, 30,000 posts, 200,000 comments. 16GB 4CPU VPS on centos/apache</issue_description>

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

@danielbachhuber Thanks for the report, @bozzmedia !

I imagine it's processing a large body of data (files or in your database) for a specific check, and is slow to update the progress indicator.

It would be nice to have a --verbose flag that gives you more visibility into what each check is doing.</comment_new>

• Fixes Introduce --verbose flag to provide more visibility into what checks are doing #170

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[swissspidy]

@copilot instead of a --verbose argument, why not make use of WP_CLI::debug(). With the second argument set to doctor, one can use --debug=doctor. Then we don't have to worry about the table formatting either.