[PHP.wasm] Major overhaul of URL rewriting and setting $_SERVER variables #2864

adamziel · 2025-11-04T21:17:14Z

The Problem

The PHP request handler wasn't correctly applying URL rewriting and setting the correct $_SERVER variables. Apache distinguishes between unrewritten and rewritten URLs when setting $_SERVER['PHP_SELF'], $_SERVER['REQUEST_URI']` and other. Before this PR, Playground wasn't doing that.

PHP Documentation on $_SERVER has some pointers, but they're far from exhaustive. I went ahead and started actual Apache and PHP Dev Server instances and noted their behavior in different scenarios, such as:

PHP Dev Server with PATH_INFO: Requesting /subdir/script.php/b.php/c.php where only /subdir/script.php exists
Apache vanilla request: Simple request to /subdir/script.php?param=value
Apache with rewrite rules: Requesting /api/v1/user/123 which rewrites to /subdir/script.php?endpoint=user&id=$1

I've found a lot of nuanced behaviors that I've described in details in the relevant contextual block comment.

Motivation for the change, related issues

As reported in #2855, the default Playground rewrite rule malforms this URL:

 /wp-content/themes/Newspaper/includes/wp-booster/wp-admin/images/plugins/tagdiv-small.png

It transforms it to just:

/wp-admin/images/plugins/tagdiv-small.png

At first I thought it's a small issue with the rewrite rule, and then I've discovered a rabbit hole of nuance.

Implementation highlights

Added a PHPRequestHandler.prepare_$_SERVER_superglobal() method that produces the right $_SERVER values given a specific request URL and its rewrite. It correctly populates REQUEST_URI, PHP_SELF, SCRIPT_NAME, PATH_INFO, and QUERY_STRING. This partially overrides what php_wasm.c do. I'd like to consolidate all that logic in a follow-up PR.
Added partial resolution logic to handle request paths such as /file.php/index.php where the full path doesn't exist but /file.php does. This matches Apache and PHP Dev Server behavior.
Added a PHPRequestHandler.#applyRewriteRules() method that applies the URL rewrite and merges the newly generated query parameters with the ones from the the original URL.

Test Coverage

Added test suites covering the same scenarios I've tested with Apache and PHP dev server. We send a request to a specific URL given some server-side rewrites or no rewrites at all, and then we confirm Playground produces $_SERVER values consistent with those servers.

adamziel · 2025-11-04T21:32:20Z

@tusharsnx btw the URL starting with /wp-content/ will not work anyway since every Playground lives at a subpath similar to /scope:my-site/. You'll need to use some WordPress helper to generate a site-relative URL, which will also solve the issue you are experiencing. I wonder if that makes this PR unnecessary, since we always expect that scope segment to come first 🤔

tusharsnx · 2025-11-05T07:12:53Z

@adamziel I'm not sure if that's also true for Playground CLI. I can see that URLs are unscoped when using wp-playground-cli server command.

The full command I'm using to start Playground server:

wp-playground-cli server --auto-mount --mount-before-install ./wordpress:/wordpress

The /wordpress installation lives alongside the code files.

This is an interesting discussion that happened in that thread. @bgrgicak Could you take a look here?

adamziel · 2025-11-05T13:28:02Z

Aha, I forgot these are also used in Playground CLI. Thank you for clarifying! Then yes, we need to address this. I actually started questioning whether we need this default rule at all. I think it's only needed on multisites? .htaccess used for single-sites installed at a /subdirectory/ seem to require knowledge about the subdirectory prefix – presumably we also need that here. In any case, I removed it to see how CI reacts and I'll also analyze that old discussion to revisit the rationale.

…r rewriting)

adamziel · 2025-11-05T17:00:39Z

This turned out to be such a rabbit hole. URL rewrites never resolved the final URL correctly. In addition, the request handler never set the $_SERVER variables correctly when a rewrite was applied. I'll be pushing a bulky update to this PR pretty soon.

…nst real outcomes from other servers

packages/php-wasm/universal/src/lib/php-request-handler.ts

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

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

brandonpayton

After reading everything, these changes look good to me. I really appreciate all the comments explaining reasoning and clarifying non-obvious bits of $_SERVER and rewrite rules. And I learned some things from reading them. :) Thank you, @adamziel!

brandonpayton · 2025-11-05T21:17:21Z

packages/playground/wordpress/src/rewrite-rules.ts

+		match: new RegExp(
+			/* The .htaccess rule does not have an explicit initial slash,
+				but it's still implied by `RewriteBase /` */
+			`^(/[_0-9a-zA-Z-]+)?` +


Why did this change from
^\/(.*?)
to
^(/[_0-9a-zA-Z-]+)?

Are there paths that worked before that will not work now?

I sourced it directly from the WordPress .htaccess rule:

^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]

(.*?) was never an accurate substitute and could have spanned multiple path segments.

(.*?) was never an accurate substitute and could have spanned multiple path segments.

Thanks for the background. And good point!

packages/php-wasm/universal/src/lib/php-request-handler.ts

packages/playground/wordpress/src/rewrite-rules.ts

packages/php-wasm/universal/src/lib/php-request-handler.ts

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

packages/playground/wordpress/src/test/rewrite-rules.spec.ts

packages/playground/wordpress/src/rewrite-rules.ts

adamziel · 2025-11-06T16:17:27Z

The only remaining failures are a timeout and memory out of bounds error that also came up in the #2834 PR – nothing related to this PR. Lovely! Let's merge!

Update the default rewrite rule

21820a0

Remove rewrite rules entirely to see how CI reacts

32746ab

adamziel added 3 commits November 5, 2025 16:43

Distinguish between REQUEST_URI (before rewriting) and PHP_SELF (afte…

3f89866

…r rewriting)

Carefully handle original and rewritten url in the php request handler

79d11a5

Thoroughly set $_SERVER variables in the request handler

6afaaf5

adamziel added 2 commits November 5, 2025 19:20

Scrutinize all the $_SERVER variables and test nuanced scenarios agai…

4b49765

…nst real outcomes from other servers

Rename request to requestWrapper

1a470e0

adamziel changed the title ~~Update the default rewrite rule~~ [PHP.wasm] Major overhaul of URL rewriting and setting $_SERVER variables Nov 5, 2025

brandonpayton reviewed Nov 5, 2025

View reviewed changes

packages/php-wasm/universal/src/lib/php-request-handler.ts Show resolved Hide resolved

brandonpayton reviewed Nov 5, 2025

View reviewed changes

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

brandonpayton reviewed Nov 5, 2025

View reviewed changes

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

adamziel added [Type] Bug An existing feature does not function as intended [Package][@php-wasm] CLI [Package][@php-wasm] Web [Package][@php-wasm] Node [Package][@php-wasm] Universal labels Nov 5, 2025

adamziel added 3 commits November 5, 2025 23:46

Call removePathPrefix() to compute fsPath

8af4922

Remove PHPRequestWrapper type

52d4582

Resolve multisite test failure

74de530

adamziel marked this pull request as ready for review November 6, 2025 00:45

brandonpayton approved these changes Nov 6, 2025

View reviewed changes

adamziel added 5 commits November 6, 2025 10:55

Adjust a few remaining tests

4e323da

Explain lack of flags implementation

c99decf

Rename prepare$_SERVER

a788a04

increase import WXR test timeout

089e21d

increase test timeouts

a13d06a

adamziel added 5 commits November 6, 2025 12:25

Explicit while() loop condition

c0d540c

replace encodeUriComponent with URLSearchParams()

38047e6

Only run partial resolution for php files

440e489

Prevent WordPress from breaking our E2E test

08821a9

Look for missing assets using the site-relative URL form

29f5e20

adamziel merged commit 897f782 into trunk Nov 6, 2025
27 of 29 checks passed

adamziel deleted the fix-rewrite-rules branch November 6, 2025 16:17

adamziel mentioned this pull request Nov 6, 2025

[PHP.wasm] ImageMagick extension #2834

Merged

[PHP.wasm] Major overhaul of URL rewriting and setting $_SERVER variables #2864

[PHP.wasm] Major overhaul of URL rewriting and setting $_SERVER variables #2864

Uh oh!

Conversation

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

Uh oh!

The Problem

Motivation for the change, related issues

Implementation highlights

Test Coverage

Uh oh!

adamziel commented Nov 4, 2025

Uh oh!

tusharsnx commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brandonpayton left a comment

Choose a reason for hiding this comment

Uh oh!

brandonpayton Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

adamziel Nov 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!

brandonpayton Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

adamziel commented Nov 4, 2025 •

edited

Loading

tusharsnx commented Nov 5, 2025 •

edited

Loading

adamziel commented Nov 5, 2025 •

edited

Loading

adamziel commented Nov 5, 2025 •

edited

Loading

adamziel Nov 6, 2025 •

edited

Loading

adamziel commented Nov 6, 2025 •

edited

Loading