Fix outdated permalinks in indexables

[leonidasmi]

Context

Summary

This PR can be summarized in the following changelog entry:

• Unblocks recent improvements in how WooCommerce handles permalinks of products assigned to multiple categories.

Relevant technical choices:

• Enhanced the Meta_Tags_Context_Memoizer::clear() function while not adding regression tests in the instructions (aside from the case where we use it, when purging product permalinks) because I have verified that the function is not used anywhere in our codebase.

Test instructions

Test instructions for the acceptance test before the PR gets merged

This PR can be acceptance tested by following these steps:

Note: Unless told otherwise, all steps require enabling the feature flag: define( 'YOAST_SEO_DYNAMIC_PRODUCT_PERMALINKS', true );

WooCommerce fix

• Have Woo (pre-10.5) and Yoast Free enabled
• Have Shop base with category as the products' permalinks
• Create the following product categories (important: with the order that I'm sharing)
  • Smartphones
  • Phones
  • Electronics
• Edit Phones and make it a child of Electronics
• Edit Smartphones and make it a child of Phones
• Create 2 products that belong to all 3 categories:
  • Product A, with Phones as the primary category
  • Product B, with Smartphones as the primary category
• Both products have a permalink of example.com/shop/electronics/phones/productName format
• We upgrade to Woo 10.5

Without this PR:

• no products have had their permalinks changed to example.com/shop/electronics/phones/smartphones/productName/
• visit the All products page in the admin and confirm the above
• visit the products' pages and confirm you're not redirected anywhere else
• confirm that the meta tags and schema attributes have the URLs of the page you're on

With this PR:

• both products have had their permalinks changed to example.com/shop/electronics/phones/smartphones/productName/
• their meta tags/canonicals/schema URLs have also been updated to the new format
• the products' indexables have now the permalink that points to the new URLs

With Woo SEO

• Repeat the above tests
• The results with this PR should be the same as is without this PR:
  • Product with Phones as primary has a permalink of example.com/shop/electronics/phones/productName format
  • Product with Smartphones as primary has a permalink of example.com/shop/electronics/phones/smartphones/productName format
  • We upgrade to Woo 10.5
  • all products keep their old permalinks

With the feature flag disabled

• Disable the feature flag and regression test this PR.

More generic testing

• With WooCommerce 10.5 and the feature flag enabled, find the indexable of a product and check its permalink, eg. http://example.com/post-example/
• Visit the post, and take a note of its meta tags and schema
  • Edit the permalink in the db, eg. http://example.com/post-example-new
• Visit the post in http://example.com/post-example
• Refresh the product only once (beware: refreshing a product and then going to see the view-source counts as two times, you can check the meta tags/schema in the developer tools, which wont re-trigger a page load
  • Check the indexable and confirm that the permalink has been reverted to the initial, proper value
  • Check that the meta tags/schema/breadcrumps/anything URL-related that Yoast SEO outputs in the frontend is the same with the first page load
• After the first page load, using Query MonitorCheck how many queries our new code is adding, which should be none
  • You can comment in and out the extra wpseo_head hook that this PR is adding to do that.
• Repeat the test with either a WooCommerce version before 10.5, or with the feature flag disabled
  • Confirm that the indexable is not reverted to the initial proper value.
  • Confirm that we still dont have extra queries.
• Now refresh any product without having touched its permalink in the db and confirm that:
  • The meta tags/schema are the same compared to before.

Relevant test scenarios

• Changes should be tested with the browser console open
• Changes should be tested on different posts/pages/taxonomies/custom post types/custom taxonomies
• Changes should be tested on different editors (Default Block/Gutenberg/Classic/Elementor/other)
• Changes should be tested on different browsers
• Changes should be tested on multisite

Test instructions for QA when the code is in the RC

• QA should use the same steps as above.

Impact check

This PR affects the following parts of the plugin, which may require extra testing:

• Indexable post builder:
  • Run the SEOO both with this PR/RC and without and compare the permalink column of indexables. You just need to check indexables for object_type=post. Clean indexables between switching plugin version.
  • Aside from checking posts or page, etc., let's also check attachments. For that we need to enable the Enable media pages setting and then run SEOO. Find all indexables with object_sub_type=attachment and compare the permalinks with this PR/RC and without. Clean indexables between switching plugin version
• Generate Home URL:
  • Enable dynamic permalinks with the add_filter( 'wpseo_dynamic_permalinks_enabled', '__return_true' ); snippet
  • Check the canonical tag in a post
  • Confirm it's the same with this PR/RC and trunk/released version
• Schema of images
  • With the Enable media pages setting both on and off, create a post with no feature image and an image in the content, check the frontend and confirm that the ImageObject node is the same with this PR/RC and without.

Other environments

• This PR also affects Shopify. I have added a changelog entry starting with [shopify-seo], added test instructions for Shopify and attached the Shopify label to this PR.
• This PR also affects Yoast SEO for Google Docs. I have added a changelog entry starting with [yoast-doc-extension], added test instructions for Yoast SEO for Google Docs and attached the Google Docs Add-on label to this PR.

Documentation

• I have written documentation for this change. For example, comments in the Relevant technical choices, comments in the code, documentation on Confluence / shared Google Drive / Yoast developer portal, or other.

Quality assurance

• I have tested this code to the best of my abilities.
• During testing, I had activated all plugins that Yoast SEO provides integrations for.
• I have added unit tests to verify the code works as intended.
• If any part of the code is behind a feature flag, my test instructions also cover cases where the feature flag is switched off.
• I have written this PR in accordance with my team's definition of done.
• I have checked that the base branch is correctly set.
• I have run grunt build:images and commited the results, if my PR introduces new images or SVGs.

Innovation

• No innovation project is applicable for this PR.
• This PR falls under an innovation project. I have attached the innovation label.
• I have added my hours to the WBSO document.

Fixes #

[thijsoo]

The only thing that could be changes is maybe using the helper. But otherwise looking at the rest of the code we use get_permalink often so its could also work.

[coveralls]

Pull Request Test Coverage Report for Build 111970befc403edb5a3508d599ed9fa88a3091fe

Details

• 25 of 42 (59.52%) changed or added relevant lines in 7 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-3.4%) to 52.964%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/repositories/indexable-repository.php	2	3	66.67%
src/integrations/front-end-integration.php	5	21	23.81%

Totals
Change from base Build 55ab5b11e3d9da1d0aea6808096d128892d203e9:	-3.4%
Covered Lines:	32485
Relevant Lines:	61373

---

💛 - Coveralls

[Copilot]

Pull request overview

This PR enables dynamic handling of WooCommerce product permalinks that have changed due to category reassignments, particularly addressing changes introduced in WooCommerce 10.5. The implementation detects permalink mismatches between the stored indexable and the current permalink, then purges and recalculates outdated permalinks to ensure meta tags, canonicals, and schema remain accurate.

Changes:

• Added permalink validation logic in Front_End_Integration to detect and update outdated product permalinks when the feature flag is enabled
• Enhanced Meta_Tags_Context_Memoizer to support clearing specific cache entries and added corresponding presentation memoizer clearing
• Moved permalink generation logic from Indexable_Post_Builder to a new Permalink_Helper method for better reusability
• Extended Indexable_Repository::reset_permalink() to support filtering by object ID

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/conditionals/dynamic-product-permalinks-conditional.php	Adds feature flag conditional for dynamic product permalinks
src/helpers/permalink-helper.php	Extracts post permalink generation into reusable helper method
src/builders/indexable-post-builder.php	Refactors to use Permalink_Helper instead of internal method
src/integrations/front-end-integration.php	Implements permalink validation and update logic with feature flag checks
src/integrations/woocommerce-product-category-permalink-integration.php	Adds conditional logic to restore legacy permalink behavior when feature flag is disabled
src/repositories/indexable-repository.php	Extends reset_permalink to accept object_id parameter
src/memoizers/meta-tags-context-memoizer.php	Adds presentation memoizer clearing and new clear_for_current_page method

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thijsoo]

CR + ACC 👍

[jrfnl]

@leonidasmi This is a breaking change, which has now broken the Video plugin.

Please fix.

[leonidasmi]

You mean the WP tests of Video? If so, here's the PR that fixes it: https://github.com/Yoast/wpseo-video/pull/1177

[jrfnl]

@leonidasmi Thanks ! Any idea when that will be merged ?

[leonidasmi]

No promises, but I'll push for it in tomorrow's standup, so this week probably

(feel free to quickly CR and merge though, if you need it merged ASAP, there's no real impact aside from tests)

[jrfnl]

Well, it LGTM, but I'm no expert in the indexables ;-)

It is blocking me, but I still have enough other things I can do before that becomes an issue. Will keep an eye on it in the mean time.

Thanks.

[thijsoo]

@jrfnl the offending video pr has been merged :)

[jrfnl]

@thijsoo @leonidasmi Thanks for the quick turn-around! Should the changelog for this change be reclassified to "Other" ? (as it is a breaking change for code based integrations)