rankmath-plugin-compatibility

Rank Math plugin compatibility

Implement a soft, hook-based compatibility layer that keeps working when Rank Math is absent or a module is disabled. Prefer WordPress and documented Rank Math hooks over internal containers, direct output, or copied plugin logic.

Workflow

1. Identify the content surface: singular CPT, taxonomy archive, virtual route, editor-only field, headless URL, or imported SEO metadata.
2. Confirm whether Rank Math is optional or a declared dependency. Keep it optional unless the product explicitly cannot function without it.
3. Register integration hooks early and idempotently.
4. Make frontend output and editor analysis agree, but do not confuse them: frontend PHP filters do not update the editor score, and editor JavaScript filters do not alter frontend tags.
5. Verify rendered HTML, not only stored meta or callback execution.
6. Test once with Rank Math active and once inactive.

Bootstrap safely

rank_math/loaded fires while the Rank Math plugin file is loading, before its plugins_loaded:14 initialization and before modules load on after_setup_theme:2. Handle both plugin load orders:

function acme_rank_math_boot(): void {
	static $booted = false;
	if ( $booted || ! defined( 'RANK_MATH_VERSION' ) ) {
		return;
	}

	$booted = true;
	add_filter( 'rank_math/frontend/title', 'acme_rank_math_title' );
}

if ( did_action( 'rank_math/loaded' ) ) {
	acme_rank_math_boot();
} else {
	add_action( 'rank_math/loaded', 'acme_rank_math_boot' );
}

Apply these rules:

• Do not call rank_math() before rank_math/loaded.
• Do not assume rank_math/loaded means active modules are instantiated. Check module-dependent classes after after_setup_theme priority 2, or simply register their hooks and let inactive modules leave them unused.
• Use RankMath\Helper::is_module_active( 'rich-snippet' ) for Schema and 'sitemap' for XML sitemaps only when the helper exists. The Schema module ID is not schema.
• Do not instantiate Rank Math frontend, Paper, Schema, or Sitemap classes yourself during normal requests.
• Do not edit Rank Math files or load files from RANK_MATH_PATH manually; its Composer autoloader owns those classes.