[XDebug Bridge] Add `--quiet` and `--verbose` options in bridge #2436

mho22 · 2025-07-28T14:13:08Z

Motivation for the change, related issues

Before this pull request, every logs were printed without control on it.

Now, By default, only the start-bridge logs are displayed in the terminal:

Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Implementation details

The --quiet option empties the logger.handlers and no output is printed.

The --verbose option will print every log. And mainly the CDP and DBGP receive and send logs useful for bridge development but too noisy for actual PHP debugging.

Testing Instructions (or ideally a Blueprint)

Normal mode

> nx run php-wasm-xdebug-bridge:dev

> node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts ./packages/php-wasm/xdebug-bridge/src/cli.ts

Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Quiet mode

> nx run php-wasm-xdebug-bridge:dev --args=--quiet

> node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts ./packages/php-wasm/xdebug-bridge/src/cli.ts --quiet

...silence...

Verbose mode

> nx run php-wasm-xdebug-bridge:dev --args=--verbose

> node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts ./packages/php-wasm/xdebug-bridge/src/cli.ts --verbose


Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

[CDP][received] {"id":1,"method":"Network.setCacheDisabled","params":{"cacheDisabled":true}}
[CDP][received] {"id":2,"method":"Network.enable","params":{"maxPostDataSize":65536,"reportDirectSocketTraffic":true}}
[CDP][received] {"id":3,"method":"Network.setAttachDebugStack","params":{"enabled":true}}
[CDP][received] {"id":4,"method":"Page.enable","params":{}}
[CDP][received] {"id":5,"method":"Page.getResourceTree","params":{}}
[CDP][received] {"id":6,"method":"Runtime.enable","params":{}}
[CDP][received] {"id":7,"method":"DOM.enable","params":{}}
[CDP][received] {"id":8,"method":"CSS.enable","params":{}}
[CDP][received] {"id":9,"method":"Debugger.enable","params":{"maxScriptsCacheSize":10000000}}
[CDP][received] {"id":10,"method":"Debugger.setPauseOnExceptions","params":{"state":"none"}}
[CDP][received] {"id":11,"method":"Debugger.setAsyncCallStackDepth","params":{"maxDepth":32}}
[CDP][received] {"id":12,"method":"Overlay.enable","params":{}}
[CDP][received] {"id":13,"method":"Overlay.setShowViewportSizeOnResize","params":{"show":true}}
[CDP][received] {"id":14,"method":"Animation.enable","params":{}}
[CDP][received] {"id":15,"method":"Autofill.enable","params":{}}
[CDP][received] {"id":16,"method":"Autofill.setAddresses","params":{"addresses":[]}}
[CDP][received] {"id":17,"method":"Profiler.enable","params":{}}
[CDP][received] {"id":18,"method":"Log.enable","params":{}}
[CDP][received] {"id":19,"method":"Log.startViolationsReport","params":{"config":[{"name":"longTask","threshold":200},{"name":"longLayout","threshold":30},{"name":"blockedEvent","threshold":100},{"name":"blockedParser","threshold":-1},{"name":"handler","threshold":150},{"name":"recurringHandler","threshold":50},{"name":"discouragedAPIUse","threshold":-1}]}}
[CDP][received] {"id":20,"method":"Emulation.setEmulatedMedia","params":{"media":"","features":[{"name":"color-gamut","value":""},{"name":"prefers-color-scheme","value":""},{"name":"forced-colors","value":""},{"name":"prefers-contrast","value":""},{"name":"prefers-reduced-data","value":""},{"name":"prefers-reduced-motion","value":""},{"name":"prefers-reduced-transparency","value":""}]}}
[CDP][received] {"id":21,"method":"Emulation.setEmulatedVisionDeficiency","params":{"type":"none"}}
[CDP][received] {"id":22,"method":"Audits.enable","params":{}}
[CDP][received] {"id":23,"method":"ServiceWorker.enable","params":{}}
[CDP][received] {"id":24,"method":"Inspector.enable","params":{}}
[CDP][received] {"id":25,"method":"Target.setAutoAttach","params":{"autoAttach":true,"waitForDebuggerOnStart":true,"flatten":true}}
[CDP][received] {"id":26,"method":"Target.setDiscoverTargets","params":{"discover":true}}
[CDP][received] {"id":27,"method":"Target.setRemoteLocations","params":{"locations":[{"host":"localhost","port":9229}]}}
[CDP][received] {"id":28,"method":"Runtime.addBinding","params":{"name":"__chromium_devtools_metrics_reporter","executionContextName":"DevTools Performance Metrics"}}
[CDP][received] {"id":29,"method":"Network.clearAcceptedEncodingsOverride","params":{}}
[CDP][received] {"id":30,"method":"Debugger.setBlackboxPatterns","params":{"patterns":["/node_modules/|^node:"],"skipAnonymous":false}}
[CDP][received] {"id":31,"method":"Page.getNavigationHistory","params":{}}
[CDP][received] {"id":32,"method":"DOMDebugger.setBreakOnCSPViolation","params":{"violationTypes":[]}}
[CDP][received] {"id":33,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":11,"url":"http://[::1]:5173/@fs/Users/mho/Work/Sandbox/Web/js/php-wasm/wordpress-playground/dist/packages/php-wasm/logger/index.js","columnNumber":0,"condition":""}}
[CDP][received] {"id":34,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":42,"url":"https://sparse.test:5173/@fs/Users/mho/Work/Sandbox/Web/js/php-wasm/wordpress-playground/dist/packages/php-wasm/web/php/jspi/php_8_2.js","columnNumber":68886,"condition":""}}
[CDP][received] {"id":35,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":4480,"url":"debugger:///VM902 client-CdekbSNg.js","columnNumber":0,"condition":""}}
[CDP][received] {"id":36,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":2,"url":"file:///Users/mho/Work/Projects/Development/Web/Professional/xdebug/template/php/xdebug.php","columnNumber":0,"condition":""}}
[CDP][received] {"id":37,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":2,"url":"file://xdebug.php","columnNumber":0,"condition":""}}
[CDP][received] {"id":38,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":2,"url":"file:///wordpress/xdebug.php","columnNumber":0,"condition":""}}
[CDP][received] {"id":39,"method":"Runtime.runIfWaitingForDebugger","params":{}}
[CDP][received] {"id":40,"method":"Page.setAdBlockingEnabled","params":{"enabled":false}}
[CDP][received] {"id":41,"method":"Emulation.setFocusEmulationEnabled","params":{"enabled":false}}
[CDP][received] {"id":42,"method":"Page.startScreencast","params":{"format":"jpeg","quality":80,"maxWidth":272,"maxHeight":1778}}
Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

mho22 · 2025-08-04T08:15:29Z

I will try to add tests before marking it as ready for review.

adamziel · 2025-08-04T15:10:49Z

Maybe --verbosity=quiet|normal|debug or so? That way we won't run into ./run-bridge --quiet --verbose conundrum. Also, we can always call logger.log() and such – output filtering can be done at the logToConsole log handler level (with some refactoring). Then, the CLI package could follow that pattern.

mho22 · 2025-08-06T11:45:24Z

@adamziel This one was a quite big refactoring. I will need a review on this. A little summary of what I had in mind when I coded these :

I set a LogVerbosity option like you suggested. Directly inside the Logger file. 3 options : quiet, normal and debug.
The default one is debug since debug accepts every severity, like before the refactoring.
When calling filterByVerbosity :

if you choose quiet no severity will be printed in the console
if you choose normal all severities except debug will be printed in the console.
if you choose debug all severities will be printed in the console.

I implemented the --verbosity option in :

The Xdebug Bridge CLI
The Playground CLI

I implemented tests in :

Logger
Xdebug Bridge
Playground CLI

I therefore have several questions :

The normal verbosity should silence more than only the debug severity ?
Should I add a new --verbosity option in the PHP Wasm CLI too ?
Should I apply these filters to every LogHandlers or only the logToConsole one ?

adamziel · 2025-08-06T12:31:03Z

packages/php-wasm/logger/src/lib/logger.ts

+			const isConsole = handler.name === 'logToConsole';
+			const isSeverityAllowed = log.severity
+				? this.filters.includes(log.severity)
+				: !!this.filters.length;
+
+			if (!isConsole || isSeverityAllowed) {
+				handler(log, ...args);
+			}


I'm confused – what's the reasoning here? Do we need special casing?

If you're asking for the isConsole line : in my last comment I wanted to know if your suggestion with --verbosity only concerned logToConsole. If not I can remove that line.

If you're asking for the isSeverityAllowed line, the severity of a log can be a LogSeverity type but also undefined. And if it is undefined, it takes the Info severity in log-to-memory. That is why I had to use a ternary operator.

I would suggest to replace the undefined severity by a Log LogServerity and in log-to-memory.ts replace:

- log.severity ?? LogSeverity.Info, + log.severity == LogSeverity.Log ? LogSeverity.Info : log.severity

in my last comment I wanted to know if your suggestion with --verbosity only concerned logToConsole.

Ah, good question! Let's target all handlers. If we want to restrict the console output while still collecting all the logs somewhere, we can do that at the logToConsole handler level.

packages/php-wasm/logger/src/lib/logger.ts

packages/playground/cli/src/run-cli.ts

adamziel · 2025-08-06T12:35:09Z

Things are looking good! I haven't tested it yet at this stage, only left a few comments – this one seems the most important.

adamziel · 2025-08-06T13:01:48Z

The normal verbosity should silence more than only the debug severity ?

I'd say normal includes all the log levels except debug.

Should I add a new --verbosity option in the PHP Wasm CLI too ?

Potentially? But not in this PR, it already covers a lot of ground.

mho22 · 2025-08-06T13:48:07Z

I'd say normal includes all the log levels except debug.

Done.

Potentially? But not in this PR, it already covers a lot of ground.

Ok! What do you think about using yargs in php-wasm/cli/main.ts and renaming the file to run-cli.ts to maintain consistency across the different CLIs? Let's talk about that in the next pull request maybe.

adamziel · 2025-08-06T23:04:59Z

Ok! What do you think about using yargs in php-wasm/cli/main.ts and renaming the file to run-cli.ts to maintain consistency across the different CLIs? Let's talk about that in the next pull request maybe.

Sounds great for a follow-up PR!

adamziel · 2025-08-07T23:23:57Z

packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts

@@ -96,7 +96,7 @@ export class BlueprintsV1Handler {
 				);
 				progressReached100 = percentProgress === 100;

-				if (!this.args.quiet) {
+				if (this.args.verbosity !== LogVerbosity.Quiet) {


Let's check it in this.writeProgressUpdate instead of before every call

adamziel · 2025-08-07T23:25:23Z

I'll test this and follow up tomorrow

adamziel · 2025-08-08T13:28:32Z

packages/php-wasm/logger/src/lib/logger.ts

+export const LogVerbosity = {
+	Normal: 'normal',
+	Quiet: 'quiet',
+	Debug: 'debug',
+} as const;


Let's not distinguish between verbosity and severity at the logger level. One concept is enough. We can decide what each verbosity means in the CLI args parser when we let the user decide. All internal methods could use severities for filtering.

adamziel · 2025-08-08T13:29:04Z

packages/php-wasm/logger/src/lib/logger.ts

+export const LogSeverity = {
+	Log: { name: 'log', level: 1 },
+	Info: { name: 'info', level: 1 },
+	Warn: { name: 'warn', level: 1 },
+	Error: { name: 'error', level: 1 },
+	Fatal: { name: 'fatal', level: 1 },
+	Debug: { name: 'debug', level: 2 },
+} as const;


Let's give each severity a unique level, e.g.

export const LogSeverity = { Fatal: { name: 'fatal', level: 0 }, Error: { name: 'error', level: 1 }, Warn: { name: 'warn', level: 2 }, Log: { name: 'log', level: 3 }, Info: { name: 'info', level: 4 }, Debug: { name: 'debug', level: 5 }, } as const;

adamziel · 2025-08-08T13:29:59Z

I've left two notes about the code design, and my only other note would be to adjust the PR title and description to reflect the larger logging refactor.

Add quiet and verbose options in Xdebug Bridge

071ffc2

mho22 mentioned this pull request Jul 28, 2025

[ php-wasm ] Follow-up on Xdebug #2315

Open

12 tasks

mho22 added [Type] Enhancement New feature or request [Package][@php-wasm] CLI [Package][@wp-playground] CLI XDebug labels Jul 28, 2025

Refine README file

400999f

mho22 changed the title ~~[XDebug Bridge] Add --quiet and --verbose options in Xdebug Bridge~~ [XDebug Bridge] Add --quiet and --verbose options in bridge Jul 28, 2025

mho22 added 2 commits August 4, 2025 12:50

Add tests

805dc23

Lint

d5c3140

mho22 marked this pull request as ready for review August 4, 2025 12:15

mho22 added 3 commits August 5, 2025 16:43

Add verbosity in logger and xdebug-bridge

436e46d

Merge branch 'trunk' into add-verbose-option-in-xdebug-bridge

f48d972

Add verbosity tests in Playground CLI

a8a6421

Merge branch 'trunk' into add-verbose-option-in-xdebug-bridge

bcf694c

adamziel reviewed Aug 6, 2025

View reviewed changes

packages/php-wasm/logger/src/lib/logger.ts Outdated Show resolved Hide resolved

adamziel reviewed Aug 6, 2025

View reviewed changes

packages/playground/cli/src/run-cli.ts Outdated Show resolved Hide resolved

Add verbosity level instead of array of filters in Logger

61908a9

adamziel reviewed Aug 7, 2025

View reviewed changes

adamziel added 2 commits August 8, 2025 15:14

Adjust how quiet is promoted to verbosity

1cdcec7

Adjust how debug is promoted to verbosity

00d7e5c

Support .logMessage() calls without an explicit severity

39c5d90

adamziel reviewed Aug 8, 2025

View reviewed changes

[XDebug Bridge] Add --quiet and --verbose options in bridge #2436

Are you sure you want to change the base?

[XDebug Bridge] Add --quiet and --verbose options in bridge #2436

Uh oh!

Conversation

mho22 commented Jul 28, 2025

Motivation for the change, related issues

Implementation details

Testing Instructions (or ideally a Blueprint)

Normal mode

Quiet mode

Verbose mode

Uh oh!

mho22 commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamziel commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mho22 commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamziel Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mho22 Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

mho22 Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adamziel commented Aug 6, 2025

Uh oh!

adamziel commented Aug 6, 2025

Uh oh!

mho22 commented Aug 6, 2025

Uh oh!

adamziel commented Aug 6, 2025

Uh oh!

adamziel Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

adamziel commented Aug 7, 2025

Uh oh!

adamziel Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

adamziel Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

adamziel commented Aug 8, 2025

Uh oh!

Uh oh!

[XDebug Bridge] Add `--quiet` and `--verbose` options in bridge #2436

[XDebug Bridge] Add `--quiet` and `--verbose` options in bridge #2436

mho22 commented Aug 4, 2025 •

edited

Loading

adamziel commented Aug 4, 2025 •

edited

Loading

mho22 commented Aug 6, 2025 •

edited

Loading

adamziel Aug 6, 2025 •

edited

Loading

mho22 Aug 6, 2025 •

edited

Loading

mho22 Aug 6, 2025 •

edited

Loading