of a single page, assembled, explained and checked.
*
* Every SEO plugin writes tags into
and then never shows them to you
* again. You find out what actually shipped by opening view-source, or by
* pasting the URL into somebody else's validator. That is the gap this fills:
* the exact tag list for one page, where each tag came from, what is wrong with
* it, and — on request — a comparison against the head the server really sends,
* which is the only way to catch a theme or a second SEO plugin writing a
* competing canonical.
*
* Two sources of truth, deliberately kept apart:
*
* 1. `plan()` reconstructs what this plugin intends to emit, using the same
* helpers the front end uses (PostSeo, SeoModule, RobotsModule). It works
* for drafts, for password-protected posts, and when loopback HTTP is
* blocked — which on hardened hosting is most of them.
* 2. `live()` fetches the URL and reads the head that was actually delivered.
* That includes everything the theme and every other plugin wrote, so it is
* the only place duplicates can be seen. It is also the one that can fail,
* and it says so rather than pretending the page has no head.
*
* @package AiRankSuite
*/
declare(strict_types=1);
namespace AiRankSuite\Modules\Seo\Services;
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
use AiRankSuite\Modules\Robots\RobotsModule;
use AiRankSuite\Modules\Seo\SeoModule;
use AiRankSuite\Modules\Social\SocialModule;
use AiRankSuite\Support\Options;
use AiRankSuite\Support\PostSeo;
use WP_Post;
final class HeadMeta {
/**
* Groups, in the order they are rendered — and the order they matter.
*
* @return array>
*/
public static function groups(): array {
return array(
array(
'id' => 'core',
'label' => __( 'Core', 'ai-rank-suite' ),
'note' => __( 'The title, the description and the canonical. If only three tags were right, these would be the three.', 'ai-rank-suite' ),
),
array(
'id' => 'robots',
'label' => __( 'Crawling & indexing', 'ai-rank-suite' ),
'note' => __( 'What search engines and AI crawlers are permitted to do with this page.', 'ai-rank-suite' ),
),
array(
'id' => 'open_graph',
'label' => __( 'Open Graph', 'ai-rank-suite' ),
'note' => __( 'What Facebook, LinkedIn, WhatsApp, Slack and Discord show when the link is pasted.', 'ai-rank-suite' ),
),
array(
'id' => 'twitter',
'label' => __( 'X / Twitter', 'ai-rank-suite' ),
'note' => __( 'The card X renders. It falls back to Open Graph for anything missing here.', 'ai-rank-suite' ),
),
array(
'id' => 'discovery',
'label' => __( 'Discovery', 'ai-rank-suite' ),
'note' => __( 'Feeds, alternates and the machine-readable pointers crawlers follow next.', 'ai-rank-suite' ),
),
array(
'id' => 'schema',
'label' => __( 'Structured data', 'ai-rank-suite' ),
'note' => __( 'The JSON-LD graph. This is the part an AI assistant reads most literally.', 'ai-rank-suite' ),
),
);
}
/**
* The whole payload for one post.
*
* @return array
*/
public static function plan( WP_Post $post ): array {
$options = new Options();
$seo = $options->get( 'seo', SeoModule::defaults() );
$robots_s = $options->get( 'robots', RobotsModule::defaults() );
$social_s = $options->get( 'social', SocialModule::defaults() );
$title = SeoModule::resolve_title( $post );
$desc = SeoModule::resolve_description( $post );
$url = PostSeo::canonical( $post );
$card = PostSeo::social_card( $post, $title, $desc );
$conflict = SeoModule::conflict();
$coexist = null !== $conflict && empty( $seo['force_output'] );
$tags = array();
// ── Core ────────────────────────────────────────────────────────────
$tags[] = self::tag(
'title',
'title',
$title,
'core',
array(
'label' => __( 'Document title', 'ai-rank-suite' ),
'limit' => 60,
'why' => __( 'The clickable line in the result and the label an assistant uses when it cites you.', 'ai-rank-suite' ),
'owner' => $coexist ? $conflict : 'airs',
)
);
$tags[] = self::tag(
'meta',
'name:description',
$desc,
'core',
array(
'label' => __( 'Meta description', 'ai-rank-suite' ),
'limit' => 160,
'why' => __( 'Not a ranking factor; it is the sales copy under the link, and the paragraph a summariser starts from.', 'ai-rank-suite' ),
'owner' => self::owner( $coexist, 'description', $conflict ),
'required' => true,
)
);
$tags[] = self::tag(
'link',
'rel:canonical',
$url,
'core',
array(
'label' => __( 'Canonical URL', 'ai-rank-suite' ),
'why' => __( 'Names the one address that should be indexed when the same page is reachable several ways.', 'ai-rank-suite' ),
'owner' => self::owner( $coexist, 'canonical', $conflict ),
'required' => true,
)
);
// ── Robots ──────────────────────────────────────────────────────────
$directives = self::robots_for( $post, $robots_s );
$tags[] = self::tag(
'meta',
'name:robots',
implode( ', ', $directives ),
'robots',
array(
'label' => __( 'Robots directives', 'ai-rank-suite' ),
'why' => __( 'Indexing and snippet permissions for this URL. max-snippet:-1 is what lets an AI answer quote you at length.', 'ai-rank-suite' ),
'owner' => 'wp',
'note' => __( 'Written by WordPress through the wp_robots filter, with this plugin\'s directives merged in.', 'ai-rank-suite' ),
)
);
// ── Open Graph ──────────────────────────────────────────────────────
$og_on = ! empty( $seo['social_tags'] );
$og = array(
'og:type' => is_page( $post->ID ) || 'page' === $post->post_type ? 'website' : 'article',
'og:title' => (string) $card['og_title'],
'og:description' => (string) $card['og_desc'],
'og:url' => $url,
'og:site_name' => (string) get_bloginfo( 'name' ),
'og:locale' => str_replace( '-', '_', get_locale() ),
'og:image' => (string) $card['og_image'],
);
if ( is_array( $card['image_meta'] ?? null ) ) {
$og['og:image:width'] = (string) (int) $card['image_meta']['width'];
$og['og:image:height'] = (string) (int) $card['image_meta']['height'];
$og['og:image:alt'] = (string) $card['image_meta']['alt'];
}
foreach ( $og as $property => $value ) {
$tags[] = self::tag(
'meta',
'property:' . $property,
$og_on ? (string) $value : '',
'open_graph',
array(
'label' => $property,
'owner' => self::owner( $coexist, 'open_graph', $conflict ),
'off' => ! $og_on,
'required' => in_array( $property, array( 'og:title', 'og:image' ), true ),
'limit' => 'og:description' === $property ? 200 : 0,
'why' => self::why( $property ),
)
);
}
// ── Twitter ─────────────────────────────────────────────────────────
$tw = array(
'twitter:card' => (string) $card['tw_card'],
'twitter:title' => (string) $card['tw_title'],
'twitter:description' => (string) $card['tw_desc'],
'twitter:image' => (string) $card['tw_image'],
);
$handle = trim( (string) ( $social_s['tw_site'] ?? '' ) );
if ( '' !== $handle ) {
$tw['twitter:site'] = '@' . ltrim( $handle, '@' );
}
foreach ( $tw as $name => $value ) {
$tags[] = self::tag(
'meta',
'name:' . $name,
$og_on ? (string) $value : '',
'twitter',
array(
'label' => $name,
'owner' => self::owner( $coexist, 'open_graph', $conflict ),
'off' => ! $og_on,
'required' => 'twitter:card' === $name,
'why' => self::why( $name ),
)
);
}
// ── Discovery ───────────────────────────────────────────────────────
$tags[] = self::tag(
'link',
'rel:alternate',
(string) get_bloginfo( 'rss2_url' ),
'discovery',
array(
'label' => __( 'RSS feed', 'ai-rank-suite' ),
'owner' => 'wp',
'why' => __( 'Several AI crawlers use the feed to notice new posts before they recrawl the site.', 'ai-rank-suite' ),
)
);
$llms = home_url( '/llms.txt' );
$tags[] = self::tag(
'link',
'rel:llms',
(bool) get_post_meta( $post->ID, '_airanksuite_exclude', true ) ? '' : $llms,
'discovery',
array(
'label' => __( 'llms.txt entry', 'ai-rank-suite' ),
'owner' => 'airs',
'why' => __( 'Whether this page is listed in the machine-readable index AI crawlers read first.', 'ai-rank-suite' ),
'note' => __( 'Not a head tag — shown here because it decides the same thing the robots directives do.', 'ai-rank-suite' ),
'meta' => false,
)
);
$amp = (string) get_post_meta( $post->ID, '_airanksuite_canonical', true );
if ( '' !== $amp && $amp !== $url ) {
$tags[] = self::tag(
'link',
'rel:canonical-override',
$amp,
'core',
array(
'label' => __( 'Canonical override', 'ai-rank-suite' ),
'owner' => 'airs',
'why' => __( 'This page points its canonical somewhere else, so it is asking not to be indexed under its own URL.', 'ai-rank-suite' ),
'meta' => false,
)
);
}
// ── Schema ──────────────────────────────────────────────────────────
$graph = self::graph( $post );
$tags[] = self::tag(
'script',
'application/ld+json',
'' === $graph ? '' : $graph,
'schema',
array(
'label' => __( 'JSON-LD graph', 'ai-rank-suite' ),
'owner' => self::owner( $coexist, 'schema', $conflict ),
'required' => true,
'why' => __( 'The only part of the page that states facts in a form a machine cannot misread.', 'ai-rank-suite' ),
'block' => true,
)
);
return array(
'url' => $url,
'public' => 'publish' === $post->post_status,
'groups' => self::groups(),
'tags' => $tags,
'source' => self::render( $tags ),
'issues' => self::issues( $tags, $post, $directives ),
'coexist' => $coexist ? $conflict : '',
'social' => $og_on,
'counts' => self::counts( $tags ),
);
}
/**
* Whether we or the other SEO plugin writes a given surface.
*/
private static function owner( bool $coexist, string $surface, ?string $conflict ): string {
if ( ! $coexist ) {
return 'airs';
}
return \AiRankSuite\Modules\Coexistence\CoexistenceModule::owns( $surface ) ? 'airs' : (string) $conflict;
}
/**
* One tag record.
*
* @param array $args Extras.
* @return array
*/
private static function tag( string $element, string $key, string $value, string $group, array $args = array() ): array {
$value = trim( $value );
$limit = (int) ( $args['limit'] ?? 0 );
$length = function_exists( 'mb_strlen' ) ? mb_strlen( $value ) : strlen( $value );
$status = 'ok';
if ( ! empty( $args['off'] ) ) {
$status = 'off';
} elseif ( '' === $value ) {
$status = ! empty( $args['required'] ) ? 'missing' : 'empty';
} elseif ( $limit > 0 && $length > $limit ) {
$status = 'long';
} elseif ( 'airs' !== ( $args['owner'] ?? 'airs' ) && 'wp' !== ( $args['owner'] ?? '' ) ) {
$status = 'delegated';
}
return array(
'element' => $element,
'key' => $key,
'label' => (string) ( $args['label'] ?? $key ),
'value' => $value,
'group' => $group,
'length' => $length,
'limit' => $limit,
'status' => $status,
'owner' => (string) ( $args['owner'] ?? 'airs' ),
'why' => (string) ( $args['why'] ?? '' ),
'note' => (string) ( $args['note'] ?? '' ),
'block' => ! empty( $args['block'] ),
// `meta:false` means "shown here for context, not literally a head tag".
'emitted' => ! isset( $args['meta'] ) || false !== $args['meta'],
);
}
/** Short explanations, kept out of the tag builder so it stays readable. */
private static function why( string $key ): string {
$map = array(
'og:title' => __( 'The headline in the link preview. It may differ from the SEO title — a share is read by a person, a result by a scanner.', 'ai-rank-suite' ),
'og:description' => __( 'Two lines under the preview headline. Cut off around 200 characters on most platforms.', 'ai-rank-suite' ),
'og:image' => __( 'Without this the link is a grey box. 1200×630 is the size every platform crops cleanly.', 'ai-rank-suite' ),
'og:type' => __( 'article for posts, website for pages. Some platforms show a byline only for article.', 'ai-rank-suite' ),
'og:locale' => __( 'Language of the preview text, so platforms pick the right typography and reading direction.', 'ai-rank-suite' ),
'og:image:width' => __( 'Lets a crawler lay out the preview before it has downloaded the image.', 'ai-rank-suite' ),
'og:image:alt' => __( 'Read aloud by screen readers on the platform, not on your site.', 'ai-rank-suite' ),
'twitter:card' => __( 'summary_large_image gets the full-width picture; summary gets a thumbnail.', 'ai-rank-suite' ),
'twitter:image' => __( 'Falls back to og:image when empty, so an empty value here is usually fine.', 'ai-rank-suite' ),
'twitter:description' => __( 'Truncated harder than Open Graph — around 125 characters.', 'ai-rank-suite' ),
);
return (string) ( $map[ $key ] ?? '' );
}
/**
* Resolve the robots directives for one post the way the front end will.
*
* @param array $settings Robots settings.
* @return array
*/
public static function robots_for( WP_Post $post, array $settings ): array {
$stored = get_post_meta( $post->ID, '_airanksuite_robots', true );
$stored = is_array( $stored ) ? $stored : array();
$out = array();
foreach ( RobotsModule::DIRECTIVES as $directive ) {
if ( in_array( $directive, $stored, true ) ) {
$out[] = $directive;
}
}
if ( in_array( 'noindex', $out, true ) ) {
// WordPress drops the preview limits once noindex is set: there is no
// snippet to limit.
return $out;
}
if ( ! in_array( 'nofollow', $out, true ) ) {
array_unshift( $out, 'follow' );
}
array_unshift( $out, 'index' );
$previews = PostSeo::previews( $post->ID );
$snippet = isset( $previews['max_snippet'] ) && '' !== (string) $previews['max_snippet']
? (int) $previews['max_snippet']
: (int) $settings['max_snippet'];
$image = ! empty( $previews['max_image_preview'] )
? (string) $previews['max_image_preview']
: (string) $settings['max_image_preview'];
$video = isset( $previews['max_video_preview'] ) && '' !== (string) $previews['max_video_preview']
? (int) $previews['max_video_preview']
: (int) $settings['max_video_preview'];
if ( ! in_array( 'nosnippet', $out, true ) ) {
$out[] = 'max-snippet:' . $snippet;
}
if ( ! in_array( 'noimageindex', $out, true ) ) {
$out[] = 'max-image-preview:' . $image;
}
$out[] = 'max-video-preview:' . $video;
return $out;
}
/**
* The JSON-LD this page will carry, pretty-printed.
*
* Built through the real graph builder rather than re-derived here: a
* preview that agrees with the front end only most of the time is worse
* than no preview, because it is trusted.
*/
private static function graph( WP_Post $post ): string {
if ( ! class_exists( \AiRankSuite\Modules\Schema\SchemaModule::class ) ) {
return '';
}
try {
$graph = ( new \AiRankSuite\Modules\Schema\SchemaModule() )->graph( $post );
} catch ( \Throwable $e ) {
return '';
}
if ( ! is_array( $graph ) || array() === $graph ) {
return '';
}
return (string) wp_json_encode(
array(
'@context' => 'https://schema.org',
'@graph' => array_values( $graph ),
),
JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
);
}
/**
* The head as it will be written, for people who trust source over tables.
*
* @param array> $tags Tags.
*/
public static function render( array $tags ): string {
$lines = array();
foreach ( $tags as $tag ) {
if ( empty( $tag['emitted'] ) || '' === $tag['value'] || 'off' === $tag['status'] ) {
continue;
}
[ $attr, $name ] = array_pad( explode( ':', (string) $tag['key'], 2 ), 2, '' );
if ( 'title' === $tag['element'] ) {
$lines[] = '' . esc_html( $tag['value'] ) . '';
continue;
}
if ( 'script' === $tag['element'] ) {
$lines[] = '';
continue;
}
if ( 'link' === $tag['element'] ) {
$lines[] = sprintf( '', esc_attr( $name ), esc_url( $tag['value'] ) );
continue;
}
$lines[] = sprintf(
'',
'property' === $attr ? 'property' : 'name',
esc_attr( $name ),
esc_attr( $tag['value'] )
);
}
return implode( "\n", $lines );
}
/**
* @param array> $tags Tags.
* @return array
*/
private static function counts( array $tags ): array {
$out = array( 'ok' => 0, 'missing' => 0, 'long' => 0, 'empty' => 0, 'off' => 0, 'delegated' => 0 );
foreach ( $tags as $tag ) {
$status = (string) $tag['status'];
$out[ $status ] = ( $out[ $status ] ?? 0 ) + 1;
}
return $out;
}
/**
* Problems worth acting on, in the order they cost you the most.
*
* @param array> $tags Tags.
* @param array $directives Robots directives.
* @return array>
*/
private static function issues( array $tags, WP_Post $post, array $directives ): array {
$by = array();
foreach ( $tags as $tag ) {
$by[ (string) $tag['key'] ] = $tag;
}
$value = static fn( string $key ): string => (string) ( $by[ $key ]['value'] ?? '' );
$issues = array();
if ( in_array( 'noindex', $directives, true ) ) {
$issues[] = array(
'level' => 'warn',
'title' => __( 'This page is set to noindex', 'ai-rank-suite' ),
'text' => __( 'It will not appear in search results, and most AI crawlers treat noindex as "do not use in answers" too. Deliberate on a thank-you page; expensive on anything else.', 'ai-rank-suite' ),
);
}
if ( in_array( 'nosnippet', $directives, true ) ) {
$issues[] = array(
'level' => 'warn',
'title' => __( 'Snippets are switched off for this page', 'ai-rank-suite' ),
'text' => __( 'nosnippet stops Google showing a description and stops AI answers quoting the page at all. It is the single most effective way to be invisible in generative results.', 'ai-rank-suite' ),
);
}
if ( '' === $value( 'name:description' ) ) {
$issues[] = array(
'level' => 'error',
'title' => __( 'No meta description', 'ai-rank-suite' ),
'text' => __( 'Search engines will invent one from the page body, and it is usually the first sentence, whatever that happens to be.', 'ai-rank-suite' ),
);
}
if ( '' === $value( 'property:og:image' ) && '' === $value( 'name:twitter:image' ) ) {
$issues[] = array(
'level' => 'warn',
'title' => __( 'No share image', 'ai-rank-suite' ),
'text' => __( 'Every link to this page renders as a grey box on LinkedIn, WhatsApp and Slack. Set a featured image or a social fallback.', 'ai-rank-suite' ),
);
}
if ( '' === $value( 'application/ld+json' ) ) {
$issues[] = array(
'level' => 'warn',
'title' => __( 'No structured data', 'ai-rank-suite' ),
'text' => __( 'The page states its facts only in prose, so a machine has to infer the author, the date and the subject rather than read them.', 'ai-rank-suite' ),
);
}
$canonical = $value( 'rel:canonical' );
$permalink = (string) get_permalink( $post );
if ( '' !== $canonical && '' !== $permalink && untrailingslashit( $canonical ) !== untrailingslashit( $permalink ) ) {
$issues[] = array(
'level' => 'warn',
'title' => __( 'The canonical points somewhere else', 'ai-rank-suite' ),
/* translators: %s: canonical URL. */
'text' => sprintf( __( 'This page asks to be indexed as %s instead of its own address. Correct for a duplicate; a silent disappearance if it was not meant.', 'ai-rank-suite' ), $canonical ),
);
}
$title = $value( 'title' );
$len = function_exists( 'mb_strlen' ) ? mb_strlen( $title ) : strlen( $title );
if ( $len > 0 && $len < 25 ) {
$issues[] = array(
'level' => 'info',
'title' => __( 'The title is very short', 'ai-rank-suite' ),
'text' => __( 'Under about 25 characters there is rarely room for both the subject and a reason to click.', 'ai-rank-suite' ),
);
}
if ( 'publish' !== $post->post_status ) {
$issues[] = array(
'level' => 'info',
'title' => __( 'Not published yet', 'ai-rank-suite' ),
'text' => __( 'These tags are what will ship when it goes live. Nothing here is on the internet yet.', 'ai-rank-suite' ),
);
}
return $issues;
}
/**
* Read the head the server actually sends and compare it with the plan.
*
* This is the check nothing else in the plugin can do: duplicates only exist
* in the rendered document. If a theme writes its own og:image and we write
* ours, both are valid on their own and both appear here.
*
* @param array> $tags Planned tags.
* @return array
*/
public static function live( string $url, array $tags ): array {
$response = wp_remote_get(
$url,
array(
'timeout' => 15,
'redirection' => 3,
'headers' => array( 'Accept' => 'text/html' ),
// A loopback request that hits our own cache plugin returns a
// stale head, which would be worse than no answer.
)
);
if ( is_wp_error( $response ) ) {
return array(
'ok' => false,
'reason' => $response->get_error_message(),
);
}
$code = (int) wp_remote_retrieve_response_code( $response );
$body = (string) wp_remote_retrieve_body( $response );
if ( $code < 200 || $code >= 300 || '' === $body ) {
return array(
'ok' => false,
'status' => $code,
/* translators: %d: HTTP status code. */
'reason' => sprintf( __( 'The server answered with HTTP %d.', 'ai-rank-suite' ), $code ),
);
}
$head = $body;
if ( preg_match( '#]*>(.*?)#is', $body, $m ) ) {
$head = $m[1];
}
$found = self::parse( $head );
// Duplicates: the same key written more than once.
$seen = array();
$duplicates = array();
foreach ( $found as $item ) {
$key = $item['key'];
if ( isset( $seen[ $key ] ) ) {
$duplicates[ $key ] = ( $duplicates[ $key ] ?? 1 ) + 1;
continue;
}
$seen[ $key ] = $item['value'];
}
// Drift: we planned a value, the page shipped a different one. Usually
// a cache, sometimes a second plugin winning the filter.
$drift = array();
foreach ( $tags as $tag ) {
if ( empty( $tag['emitted'] ) || '' === $tag['value'] || 'off' === $tag['status'] || ! empty( $tag['block'] ) ) {
continue;
}
$key = (string) $tag['key'];
if ( ! isset( $seen[ $key ] ) ) {
$drift[] = array(
'key' => $key,
'label' => (string) $tag['label'],
'planned' => (string) $tag['value'],
'live' => '',
'kind' => 'absent',
);
continue;
}
if ( trim( html_entity_decode( $seen[ $key ], ENT_QUOTES, 'UTF-8' ) ) !== trim( (string) $tag['value'] ) ) {
$drift[] = array(
'key' => $key,
'label' => (string) $tag['label'],
'planned' => (string) $tag['value'],
'live' => $seen[ $key ],
'kind' => 'differs',
);
}
}
$dupes = array();
foreach ( $duplicates as $key => $count ) {
$dupes[] = array(
'key' => $key,
'count' => $count,
);
}
return array(
'ok' => true,
'status' => $code,
'tags' => array_slice( $found, 0, 200 ),
'duplicates' => $dupes,
'drift' => array_slice( $drift, 0, 30 ),
'jsonld' => (int) preg_match_all( '#