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( '#]+application/ld\+json#i', $head ), 'bytes' => strlen( $head ), ); } /** * Pull meta/link/title out of a head fragment. * * A regex, not a DOM parser: the head we are handed is frequently invalid * HTML (unclosed tags from a theme, a stray `<` in a description) and * DOMDocument's recovery would silently drop exactly the tags worth seeing. * * @return array> */ private static function parse( string $head ): array { $out = array(); if ( preg_match( '#]*>(.*?)#is', $head, $m ) ) { $out[] = array( 'key' => 'title', 'element' => 'title', 'value' => trim( wp_strip_all_tags( $m[1] ) ), ); } if ( preg_match_all( '#]*>#i', $head, $matches ) ) { foreach ( $matches[0] as $raw ) { $attr = 'name'; $name = ''; if ( preg_match( '#\bproperty\s*=\s*["\']([^"\']+)["\']#i', $raw, $p ) ) { $attr = 'property'; $name = $p[1]; } elseif ( preg_match( '#\bname\s*=\s*["\']([^"\']+)["\']#i', $raw, $p ) ) { $name = $p[1]; } else { continue; } $value = ''; if ( preg_match( '#\bcontent\s*=\s*["\']([^"\']*)["\']#i', $raw, $c ) ) { $value = $c[1]; } $out[] = array( 'key' => $attr . ':' . $name, 'element' => 'meta', 'value' => trim( $value ), ); } } if ( preg_match_all( '#]*>#i', $head, $matches ) ) { foreach ( $matches[0] as $raw ) { if ( ! preg_match( '#\brel\s*=\s*["\']([^"\']+)["\']#i', $raw, $r ) ) { continue; } $href = ''; if ( preg_match( '#\bhref\s*=\s*["\']([^"\']*)["\']#i', $raw, $h ) ) { $href = $h[1]; } $out[] = array( 'key' => 'rel:' . strtolower( trim( $r[1] ) ), 'element' => 'link', 'value' => trim( $href ), ); } } return $out; } }