Do not rewrite fragment-only URLs on import

[mauteri]

The problem

A reference like #section points within the document that contains it. It has no host and no path, so there is no origin to migrate.

wp_rewrite_urls() resolves every URL against the base URL before consulting the mapping. For a fragment-only reference that resolution produces https://old-site.com/current-page#section, which then matches is_child_url_of() and gets rewritten against the new home:

in	out
<a href="#section">	<a href="/#section">
<a href="#add-to-calendar">	<a href="/#add-to-calendar">
<a href="#">	<a href="/">

The last one is the worst: the fragment is dropped entirely, so an in-page anchor becomes a link to the site root.

Why it matters

Beyond the broken links, this breaks block validation. Any block whose saved markup contains a fragment-only href (accordions, tab and anchor navigation, "jump to" links, and blocks that use # as a JavaScript-handled placeholder) no longer matches its save() output after an import, and the editor shows "This block contains unexpected or invalid content."

The workaround people land on is disabling URL rewriting altogether:

add_filter( 'wp_import_options', function ( $options ) {
    $options['rewrite_urls'] = false;
    return $options;
} );

That is a heavy price for one class of URL, and it gives up the migration for every genuine link in the content.

The fix

Skip fragment-only references before the mapping is consulted.

The guard deliberately reads get_raw_url() rather than the parsed URL, because parsing is what destroys the distinction: once #section has been resolved against the base it is indistinguishable from an ordinary same-site link, which is exactly why the current code rewrites it.

Scoped to references that are only a fragment. A URL carrying a fragment alongside a host or path still rewrites, and still keeps its fragment:

https://old-site.com/page#section  ->  https://new-site.com/page#section

Tests

phpunit/tests/rewrite-urls.php covers fragment-only hrefs in both markup and block attributes, plus the two cases that must keep working (absolute URL, absolute URL carrying a fragment).

Verified they fail before the change and pass after:

without the fix                       with the fix
[FAIL] named fragment                 [PASS] named fragment
[FAIL] bare hash                      [PASS] bare hash
[FAIL] hyphenated fragment            [PASS] hyphenated fragment
[FAIL] fragment in a block attribute  [PASS] fragment in a block attribute
[PASS] absolute + fragment            [PASS] absolute + fragment
[PASS] absolute                       [PASS] absolute

The two controls passing in both columns is the part that matters: the guard does not over-correct.

Notes

• This code is also in WordPress/php-toolkit (components/DataLiberation/URL/functions.php), vendored here under src/php-toolkit/. Happy to open the matching PR there so the two do not diverge, just say the word.
• Related, not fixed here: query-only references have the same shape. <a href="?filter=all"> currently becomes <a href="/?filter=all">, which likewise moves the link from the current page to the site root. I left it alone to keep this change to the reported behavior, but it may be worth the same treatment.
• phpcs --standard=phpcs.xml.dist is clean on both files. I could not run the PHPUnit suite locally (the pinned PHPUnit predates my PHP version, as CONTRIBUTING.md notes), so those run on CI.

[mauteri]

Flagging the red checks so they don't get misread as fallout from this change: they are pre-existing and unrelated to the diff.

Every failing job dies in composer install, before a single test runs:

Root composer.json requires phpunit/phpunit ^5.7.21 || ^6.5 || ^7.5 ... but these were not loaded, because they are affected by security advisories (PKSA-z3gr-8qht-p93v)

Composer blocks advisory-affected packages by default now, and the pinned PHPUnit range is entirely within that advisory, so dependency resolution fails outright.

master has the same failures on its own scheduled runs, going back over a month:

run	date	result
29709876418	2026-07-20	failure
29215890001	2026-07-13	failure
28760885388	2026-07-06	failure
28342218932	2026-06-29	failure
27923492015	2026-06-22	failure

The failing job names line up too (PHP 7.2 - WP 5.2, PHP 8.0 - WP 5.6, PHP 8.2 - WP 6.2, and so on).

Meanwhile everything that did manage to install and run on this PR passed: all three E2E shards, plus WP latest, WP trunk, PHP 8.4 - WP 6.7, and the PHP 8.0/8.1/8.3 - WP latest jobs.

Happy to open a separate PR unblocking CI if that would help. The options are roughly: allow the advisory through config.policy.advisories, or move the dev dependency onto a PHPUnit version outside the advisory range via yoast/phpunit-polyfills. That felt like it belonged in its own change rather than bundled in here.

[carstingaxion]

This is how a regular core/navigation-link block looks in a wxr file and it gets wilder with every safe.

[desrosj]

Happy to open a separate PR unblocking CI if that would help. The options are roughly: allow the advisory through config.policy.advisories, or move the dev dependency onto a PHPUnit version outside the advisory range via yoast/phpunit-polyfills. That felt like it belonged in its own change rather than bundled in here.

It looks like 582b8a3 / #264 fixed this within the workflow file, so merging/rebasing should fix those failures. However, it was not fixed within the composer.json file itself (which I think is the proper and preferred way to address this across all usage of composer). The PKSA-z3gr-8qht-p93v advisory is specifically about .phpt files which are used by PHP core. Since we don't use these here, I think it's fine to update composer.json. Let's do so in a separate PR and address the workflow file as well.

TIL about the shift from config.audit.ignore to config.policy.advisories. The former is in Core today. But updating would require contributors to use Composer 2.10+. Need to think about that more. Totally unrelated to this PR, though.

This code is also in WordPress/php-toolkit (components/DataLiberation/URL/functions.php), vendored here under src/php-toolkit/. Happy to open the matching PR there so the two do not diverge, just say the word.

I'm not that familiar with the php-toolkit, or how it has been maintained within this plugin. But looking at the commit history, it seems that changes are made in the toolkit first and then merged back into this repo (see #243). I think we should look to merge this upstream first and then merge this here.

Also outside of the scope for this PR, but it would be really nice for the toolkit to be pinned as a dependency. It would make updating and managing that much easier.

[mauteri]

Rebased on master to pick up #264, so the checks are running against the workflow fix now. The toolkit half is up at WordPress/php-toolkit#320. Once that lands I'll refresh this PR from it so the vendored copy matches. I'll open the composer.json and workflow PR separately as well.

[mauteri]

The composer.json half is #267: the allowance moves into composer.json and the two workflow steps that only existed to work around the block come out.

[zaerl]

The PR is ok, thanks for it. Just just change the domain names.

[zaerl]

Please don't use real domain names in tests. example.com and similar is ok.

[mauteri]

Switched to old.example.com and new.example.org.

[akirk]

Thanks for your contribution! I agree this is a bug that should be fixed but in my opinion the logic that detects the fragment-only URL belongs in PHP toolkit.

[akirk]

I think we should not analyze the raw URL here. What about this (after adding it to WordPress/php-toolkit#320):

Suggested change

	$raw_url = $p->get_raw_url();
	if ( is_string( $raw_url ) && 0 === strpos( $raw_url, '#' ) ) {
	if ( $p->is_fragment_only_reference() ) {

[mauteri]

Done. It uses $p->is_fragment_only_reference() from WordPress/php-toolkit#320, mirrored into the vendored copy.