My social cards were lying to me for two days, and the bug report that finally cracked it was one sentence: "the patch is in the HTML, but the card never changes."
The setup
I run a PHP tour-directory site with a shared head emitter - one function, djc_seo_render_head(), reads a $djcSeo array and prints every tag you'd want: title, canonical, Open Graph, Twitter card. Clean architecture. One place to render, every page feeds it.
Every page that didn't configure an image got a sensible default. Every page that did passed its image through the array. Except two template families - genre hubs and tag pages - where the social card was the same stock photo on every single URL.
The wrong fix (the one that verified green)
I did what you do: opened the template, found the head, and echoed a fresh og block right after the metadata include.
echo '<meta property="og:image" content="' . $cardUrl . '">' . "\n";
Deployed it, pulled the page, and there it was in view-source - my dynamic URL, sitting in the head where it belonged. Shipped. Verified. Moved on.
The card never changed.
What scrapers actually see
Here's the part I knew and didn't apply: most scrapers take the first og:image they find and stop reading. My template wasn't just rendering my shiny new block - it was running a shared emitter first, which obediently printed the default image before my block ever executed.
Two og:image sets in one head. Mine was the second one. The second one is a lie.
The bug wasn't "missing tag." The bug was "duplicate tag." Those verify differently: grep for the tag, and your patch looks like a success. Count the tags, and it was a failure the whole time.
Reading the contract
So I stopped patching HTML and read the emitter instead. Turned out the architecture I'd been side-stepping was designed for this:
$ogImageRaw = djc_seo_sanitize_og_image_url(
(string) ($seo['og_image'] ?? djc_default_share_image())
);
The emitter doesn't hardcode anything. It renders whatever's in $djcSeo['og_image']. The artist pages on the same site were already feeding dynamic card URLs through this exact path, and it worked.
The fix was never "print more tags." It was "set the variable earlier":
$djcSeo['og_image'] = 'https://example.com/og.php?a=genre-' . rawurlencode($genreSlug);
// ...emitter runs later, once, and renders it
One line of intent instead of five lines of markup. The emitter even added the image dimensions for free, because it knows its own card size.
The needle that matched the wrong line
Of course, it wasn't quite one line. The template had grown two branches over the years, each with its own build-and-render sequence - and the two render calls were byte-identical except for leading whitespace. Four spaces on one branch, none on the other.
My first patch anchored on the indented variant. Needle count: 1, exactly as expected. Lint: green. Deployed.
Still the default image.
The template has a render-once guard - the first render call wins, later ones no-op. And I'd patched the second one. The verification lesson survived the round-trip: my guard said "matched once," which is not the same question as "matched the line that runs." Two branches that differ by whitespace will pass any needle count you throw at them.
The final fix injected the override before both render calls. Same block, two anchors, both counted, lint-checked with automatic restore on failure.
What I actually learned
- Verify like the consumer. A scraper reads your page the way it wants to, not the way you wrote it. "The tag is present" and "the tag will be used" are different assertions.
- Read the emitter's contract before injecting markup into its output. If there's a variable feeding the renderer, that variable is the API. Echoing HTML around it is fighting your own architecture.
- Duplicates are a failure mode, not a curiosity. Any patch that can add a second instance of something a consumer reads first-from-top needs a count, not a grep.
- Needles that ignore whitespace are a trap in templates with copy-paste history. If your codebase has two generations of the same pattern, your anchor has to be checked against every generation - including the one with different indentation.
The end state: every genre and tag page serves exactly one og:image set, pointing at a dynamically rendered card, through the same emitter every other page uses. And the debug script I run before declaring og victory now checks three things: is the tag present, how many are there, and which one is first.
Because the second one is a lie.