Add wp-env SPX profiler option #70693
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Unlinked AccountsThe following contributors have not linked their GitHub and WordPress.org accounts: @cursoragent. Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases. If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
nerrad
added
[Type] Performance
nerrad
force-pushed
the
add/pull-request-for-wpenv-spx-option
branch
from
b9eecb4 to
af310d7
Compare
|
Size Change: 0 B Total Size: 1.91 MB ℹ️ View Unchanged
|
|
Flaky tests detected in 9fe6a4c. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/16890746910
|
Contributor
|
I don't feel qualified to judge the usefulness of this addition. :) It's the first time I hear about SPX, so naturally my first reaction is "why is xdebug not enough?". I see that performance is the most salient argument, and perhaps the Web interface contributes to ease of use. I'd like to hear, in your words, what compels you towards SPX, and how xdebug can't get us there. My concern here is that, if you don't have a good argument base, what stops us from supporting n + 1 frameworks in general? Mind you, I'm open to the addition, but there are probably better people to say. Lastly, I'm also a little wary of not knowing how stable the dependency (https://github.com/NoiseByNorthwest/php-spx) is, although — if we're honest — we can't claim that PECL (for xdebug) or Docker Hub (for phpMyAdmin) are inherently safer. |
Contributor
|
The greatest advantage php-spx has over xdebug is it supports sampling profiling. This is when you set the profiler to sample on a time interval, which means that it wakes up every so often and records what is happening, rather than measuring every function call. If you're concerned with wall time, then xdebug's behavior of measuring every function call will overweight small functions that are called very often, because each function call induces instrumentation overhead. High level example: Even though both programs might be very comparable in the real world run time, xdebug (or any non-sampling profiler) is prone to say that Example B is much slower than Example A, when it's not the case. This might misdirect your attention to things that don't matter. Sampling profiling is a way to try to overcome this limitation of profiling by giving a more accurate picture of where time is actually spent (at the tradeoff of losing measurement resolution.) SPX, in my experience, has been a easy to use, powerful profiler that implements it. It has nice visualizations too. |
Contributor
|
@mreishus: thanks, that's very useful. |
jsnajdr
approved these changes
Aug 11, 2025
| * @return {string} The SPX config -- can be an empty string when it's not used. | ||
| */ | ||
| function getSpxConfig( spxMode = 'off', phpVersion, service ) { | ||
| if ( spxMode === 'off' || service === 'cli' ) { |
Member
There was a problem hiding this comment.
I'm curious why the analogous getSpxConfig doesn't have this service check and installs xdebug happily also in the CLI container. Probably because it actually makes sense to debug a wp-cli run. Maybe it also makes sense to profile a wp-cli run? I don't know.
Contributor
Author
There was a problem hiding this comment.
Easy enough to change in a future PR if it's something needing executed on the CLI service, but for now doesn't seem to be, and like you, I also don't know whether profiling would be needed here (or if SPX is the right tool for that).
Member
There was a problem hiding this comment.
Perfectly fine to keep this as-is, I was mostly just thinking aloud 🙂
packages/env/lib/init-config.js
Outdated
|
|
||
| return ` | ||
| # Install SPX profiler | ||
| RUN apt-get update && apt-get install -y git zlib1g-dev |
Member
There was a problem hiding this comment.
There are existing usages of apt-get in this init-config.js file and they always run as apt-get -qy, i.e., be quiet and say yes to everything.
It would be also nicer if the two apt-get commands ran as independent RUN lines.
packages/env/lib/parse-spx-mode.js
Outdated
| return 'enabled'; | ||
| } | ||
|
|
||
| if ( ! SPX_MODES.some( ( realMode ) => realMode === value ) ) { |
Member
There was a problem hiding this comment.
Here you can write just ! SPX_MODES.includes( value ).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
Implements SPX (Simple Profiling eXtension) support in the
@wordpress/envpackage, providing lightweight PHP profiling capabilities with a built-in web UI.Why?
SPX offers a more lightweight alternative to Xdebug for PHP profiling, with minimal performance overhead and an intuitive web-based interface. This allows developers to profile their WordPress applications without the significant performance impact that Xdebug can have.
How?
parse-spx-mode.jsto handle SPX configuration options similar to the existing Xdebug implementationstartcommand with--spxflag support and proper mode parsinginit-config.jsto install SPX dependencies (including ZLIB development headers) and configure the extensionThe implementation follows the same pattern as the existing Xdebug integration, ensuring consistency with the codebase architecture.
Testing Instructions
npx wp-env start --spx(ornpm run env start -- --spx) to enable SPX profilinghttp://localhost:8888/?SPX_KEY=dev&SPX_UI_URI=/npx wp-env start --spx=disabledto disable profilingNote: initial version of this was created using Cursor.