Moving custom code from Rank Math or Yoast SEO

This page is for site builders and developers whose theme or plugins contain code written for Rank Math or Yoast SEO. Most Rank Math code keeps working without changes, because Anansi fires the same rank_math/… filters with the same arguments. Yoast SEO code does not: Anansi fires none of Yoast’s wpseo_* filters, so that code has to be moved to the anansi/… hooks. The page also covers reading meta, breadcrumb functions, and what Anansi deletes on uninstall.

Before you start

1. Keep the old plugin active and leave Anansi in preview mode.
2. Run wp anansi snapshot save before-switch to record what the site prints now.
3. Import the data: wp anansi import rank-math (or yoast, aioseo, seopress, tsf, redirection). The import never changes the old plugin’s data.
4. Check your custom code with wp anansi preview <url> and wp anansi snapshot compare before-switch --preview. On a preview request Anansi fires the Rank Math filters even while Rank Math is active, so you see what your Rank Math code will do after the switch.
5. Deactivate the old plugin, then wp anansi mode live.

Code written for Rank Math

Filters that keep working

When Rank Math is not active, Anansi fires these Rank Math hooks with the same arguments, right after its own anansi/… hook. Most also run on preview requests. The full list, with the exact conditions, is in hooks.md.

If a Rank Math hook is not in the full list, Anansi does not fire it. One example: rank_math/frontend/disable_adjacent_rel_links. Use anansi/disable_adjacent_rel_links instead.

Should you rename your hooks?

You do not have to. Moving to the anansi/… names is still a good idea when you touch the code anyway:

• The anansi/… hook always runs when Anansi builds that output. A few Rank Math names do not run on preview requests (see the list above).
• If Rank Math is reactivated later, Anansi steps back and stops firing the Rank Math names, so your code then runs only for Rank Math again.
• Anansi-only hooks, such as anansi/meta/sources and anansi/head/tags, have no Rank Math version.

To run on both plugins during the move, hook both names with the same callback. Anansi never fires the Rank Math name while Rank Math prints the page, so the callback does not run twice for one output:

foreach ( array( 'rank_math/frontend/description', 'anansi/description' ) as $hook ) {
    add_filter( $hook, 'mytheme_seo_description' );
}

On a preview request (Rank Math still active), Anansi fires both names for its own output. If your callback is not safe to run twice on the same value, hook only one name.

Rank Math classes and functions

Anansi does not define Rank Math’s PHP classes, such as RankMath\Helper or RankMath\Paper\Paper. Code that calls them must check class_exists() first, or move to the Anansi equivalents:

Code written for Yoast SEO

Anansi does not fire Yoast’s filters. Move each one to its Anansi hook. The arguments differ, so check each callback against hooks.md.

Yoast template variables use %%title%%; Anansi uses %title%. The importer converts stored templates and per-post titles. Variables in your own code must be changed by hand. Port custom Yoast variables registered with wpseo_register_var_replacement() to anansi/vars/{name} filters (see hooks.md).

Yoast’s meta is not read through live. Anansi only reads its own keys and Rank Math’s. Run wp anansi import yoast to copy the values into _anansi_* keys, or, for plain-text fields such as the title and description, map single keys with anansi/meta/sources when the values hold no %%variables%%.

Reading SEO meta

Before the switch, code may read rank_math_* or _yoast_wpseo_* meta directly. After the switch, new edits are saved to _anansi_* keys, so direct reads of the old keys miss them. Read through Anansi instead:

function mytheme_seo_description( $post_id ) {
    if ( class_exists( 'Anansi_Meta' ) ) {
        return (string) Anansi_Meta::post( $post_id, 'description' );
    }
    return (string) get_post_meta( $post_id, 'rank_math_description', true );
}

Anansi_Meta::post() tries _anansi_description, then rank_math_description, then your anansi/meta/sources keys. See functions.md.

Meta key names match Rank Math’s after the prefix: rank_math_title → _anansi_title, rank_math_robots → _anansi_robots, rank_math_primary_category → _anansi_primary_category. The one exception is rank_math_news_sitemap_robots → _anansi_news_robots.

Breadcrumb functions

Themes that call the old plugin’s breadcrumb function keep working. When Anansi is in charge and the old plugin is gone, Anansi defines:

They print Rank Math’s markup (<nav class="rank-math-breadcrumb">). If your CSS targeted Yoast’s or AIOSEO’s markup, adjust it or rebuild the HTML with the anansi/breadcrumb/html filter. Keep your function_exists() checks: the functions exist only on front-end page requests while Anansi is in charge. Details in functions.md.

Redirects

While Rank Math’s redirect table is still there and not imported, Anansi reads it (read-only) and answers those redirects too. wp anansi redirects list --source=rank-math shows them. Importing copies them into Anansi’s own tables. Rank Math’s table is never changed.

Code that hooked rank_math/redirection/pre_search keeps working once Rank Math is inactive. Code that wrote into Rank Math’s tables directly must move to wp anansi redirects add or Anansi’s admin screen; Anansi’s table layout is internal.

Uninstall behaviour

Deactivating Anansi removes its scheduled video lookups and IndexNow sends, and makes WordPress rebuild rewrite rules on the next request. It deletes no data.

Deleting Anansi from the Plugins screen runs uninstall.php. On multisite it runs for every site. It deletes only Anansi’s own data:

Anansi never touches another plugin’s data, on uninstall or at any other time. That includes rank_math_* meta and options, Rank Math’s redirect table, _yoast_wpseo_* meta, wpseo* options, and the data of All in One SEO, SEOPress, The SEO Framework and Redirection. If you remove Anansi and reactivate the old plugin, the old plugin finds its data as it left it. Changes made in Anansi after the switch stay in Anansi’s keys and are deleted with it.

If you want to keep Anansi’s data, deactivate the plugin instead of deleting it.