thinkrank / includes / frontend / class-schema-graph.php

class-schema-graph.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 2.7.0, at includes/frontend/class-schema-graph.php

1,653 lines 57.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Schema Graph Collector
4	*
5	* Single assembly point for every piece of JSON-LD ThinkRank emits on a request.
6	*
7	* Four subsystems used to write structured data independently — the Schema
8	* Manager (deployed per-post rows), the post-type-wide Global SEO output, the
9	* Gutenberg FAQ block and the Elementor FAQ widget. Each echoed its own
10	* <script> tag, so one URL could carry several page-level entities that never
11	* referenced each other, including two FAQPage entities with different
12	* questions (#355).
13	*
14	* Producers now register here instead of echoing. One late wp_head pass picks
15	* the page-level entity by source precedence — dropping the losing source, but
16	* keeping entities deployed alongside the winner — merges every FAQ source into
17	* one FAQPage, assigns stable @id values, links the nodes together and emits a
18	* single @graph.
19	*
20	* @package ThinkRank\Frontend
21	* @subpackage SEO
22	* @since 1.32.0
23	*/
24
25	declare(strict_types=1);
26
27	namespace ThinkRank\Frontend;
28
29	// Prevent direct access
30	if (!defined('ABSPATH')) {
31	exit;
32	}
33
34	/**
35	* Collects and emits ThinkRank's structured data as one linked @graph.
36	*
37	* @since 1.32.0
38	*/
39	class Schema_Graph {
40
41	/**
42	* Schema context URL.
43	*/
44	private const SCHEMA_CONTEXT = 'https://schema.org';
45
46	/**
47	* Entity types that describe the site rather than the current page.
48	*
49	* These get a home-scoped @id so the same entity keeps one identity on
50	* every URL. WebSite and Organization are handled explicitly alongside
51	* these because they also seed isPartOf/publisher links (#471).
52	*
53	* @since 1.16.0
54	* @var string[]
55	*/
56	private const SITE_LEVEL_TYPES = ['LocalBusiness', 'Person'];
57
58	/**
59	* Which source wins when several subsystems describe the page.
60	*
61	* Lower wins. Per-post schema deployed from the editor's Schema tab is a
62	* deliberate per-post decision, so it outranks the post-type-wide default.
63	*
64	* @var array<string,int>
65	*/
66	private const PRIMARY_PRECEDENCE = [
67	'schema_manager' => 10,
68	'global_seo' => 20,
69	];
70
71	/**
72	* Types that can legitimately be the entity a URL is about.
73	*
74	* Anything outside this set — Organization, Person, WebSite, LocalBusiness,
75	* or a type a future release starts deploying — is emitted as a supporting
76	* node instead of competing. Deliberately an allowlist: an unrecognised type
77	* demoted to supporting merely adds a node, whereas letting a non-page-level
78	* type win the slot deletes the page's real entity.
79	*
80	* @var array<int,string>
81	*/
82	private const PAGE_LEVEL_TYPES = [
83	'Article', 'BlogPosting', 'NewsArticle', 'ScholarlyArticle', 'TechArticle',
84	'TechnicalArticle', 'Report', 'WebPage', 'AboutPage', 'ContactPage',
85	'ProfilePage', 'ItemPage', 'FAQPage', 'QAPage', 'CollectionPage',
86	'Product', 'Event', 'Recipe', 'Course', 'JobPosting', 'SoftwareApplication',
87	'Book', 'Movie', 'Service', 'ImageObject', 'VideoObject',
88	];
89
90	/**
91	* Types that may carry a `breadcrumb` property.
92	*
93	* Schema.org limits `breadcrumb` to WebPage and its subtypes. Attaching it
94	* to a BlogPosting, Product or Recipe primary fails validation with
95	* "Unexpected property" on every URL; the standalone BreadcrumbList node is
96	* emitted either way (#693).
97	*
98	* @since 2.7.0
99	* @var array<int,string>
100	*/
101	private const BREADCRUMB_TYPES = [
102	'WebPage', 'AboutPage', 'CheckoutPage', 'CollectionPage', 'ContactPage',
103	'FAQPage', 'ItemPage', 'MedicalWebPage', 'ProfilePage', 'QAPage',
104	'RealEstateListing', 'SearchResultsPage', 'MediaGallery', 'ImageGallery',
105	'VideoGallery',
106	];
107
108	/**
109	* Gutenberg FAQ block name.
110	*/
111	private const FAQ_BLOCK = 'thinkrank/faq';
112
113	/**
114	* Elementor FAQ widget name.
115	*/
116	private const FAQ_WIDGET = 'thinkrank-faq';
117
118	/**
119	* Bricks FAQ element name.
120	*
121	* @since 2.3.1
122	*/
123	private const FAQ_BRICKS_ELEMENT = 'thinkrank-faq';
124
125	/**
126	* The Beaver Builder FAQ module's slug, as stored in its layout nodes.
127	*
128	* Matches `ThinkRank_Beaver_FAQ_Module::SLUG`. Duplicated as a literal
129	* rather than referenced, because that class extends `FLBuilderModule` and
130	* so cannot be loaded at all when Beaver Builder is inactive — which is
131	* exactly the site that still has a stored layout, after a builder switch.
132	*/
133	private const FAQ_BEAVER_MODULE = 'thinkrank-faq';
134
135	/**
136	* Third-party Elementor widgets that publish their own FAQPage.
137	*
138	* Maps widgetType to the setting whose 'yes' arms that widget's FAQ schema,
139	* so an accordion used purely as an accordion never suppresses ours.
140	*
141	* @since 2.1.0
142	* @var array<string,string>
143	*/
144	private const FOREIGN_FAQ_WIDGETS = [
145	// Essential Addons for Elementor — Advanced Accordion.
146	'eael-adv-accordion' => 'eael_adv_accordion_faq_schema_show',
147	];
148
149	/**
150	* Bricks elements that publish their own FAQPage.
151	*
152	* Bricks is a theme, not a plugin, and its accordions are core elements
153	* rather than a third-party add-on — so unlike FOREIGN_FAQ_WIDGETS this is
154	* a plain list: they share one gate, the `faqSchema` setting, and the
155	* per-element part of the check is whether the element has usable items
156	* (see bricks_element_publishes_faq()).
157	*
158	* @since 2.3.1
159	* @var string[]
160	*/
161	private const FOREIGN_FAQ_BRICKS_ELEMENTS = ['accordion', 'accordion-nested'];
162
163	/**
164	* Singleton instance.
165	*
166	* @var self\|null
167	*/
168	private static ?self $instance = null;
169
170	/**
171	* Memoised master switch, or null when it has not been read this request.
172	*
173	* @since 2.7.0
174	* @var bool\|null
175	*/
176	private static ?bool $master_switch_on = null;
177
178	/**
179	* Competing page-level entities: ['rank' => int, 'schema' => array, 'type' => string].
180	*
181	* @var array<int,array>
182	*/
183	private array $primary_candidates = [];
184
185	/**
186	* Non-competing nodes (Organization, WebSite, BreadcrumbList, HowTo, …).
187	*
188	* @var array<int,array>
189	*/
190	private array $supporting = [];
191
192	/**
193	* Merged FAQ questions, keyed by normalized question text.
194	*
195	* @var array<string,array>
196	*/
197	private array $faq_entities = [];
198
199	/**
200	* Memoized answer to "should this request emit a FAQPage at all?".
201	*
202	* @since 2.1.0
203	* @var bool\|null
204	*/
205	private ?bool $emit_faqpage = null;
206
207	/**
208	* Whether FAQ content was taken from the rendered post body (block/widget),
209	* meaning those producers must not emit their own duplicate script.
210	*
211	* @var bool
212	*/
213	private bool $absorbed_content_faq = false;
214
215	/**
216	* Guards against collecting the post's FAQ content more than once.
217	*
218	* @var bool
219	*/
220	private bool $faq_collected = false;
221
222	/**
223	* Whether a producer has committed to rendering this graph on the request.
224	*
225	* Lazy FAQ collection is gated on it: absorbing a block's questions into a
226	* graph that will never be emitted would silence the block and publish
227	* nothing in its place.
228	*
229	* @var bool
230	*/
231	private bool $render_scheduled = false;
232
233	/**
234	* Guards against a second render on the same request.
235	*
236	* @var bool
237	*/
238	private bool $rendered = false;
239
240	/**
241	* Get the shared instance.
242	*
243	* @since 1.32.0
244	* @return self
245	*/
246	public static function instance(): self {
247	if (null === self::$instance) {
248	self::$instance = new self();
249	}
250
251	return self::$instance;
252	}
253
254	/**
255	* Discard the shared instance. Test seam.
256	*
257	* @since 1.32.0
258	* @return void
259	*/
260	public static function reset(): void {
261	self::$instance = null;
262	// Or a test that seeds the switch inherits the previous test's answer.
263	self::$master_switch_on = null;
264	}
265
266	/**
267	* Register a candidate for the page's single page-level entity.
268	*
269	* A FAQPage is never a candidate in its own right — its questions are merged
270	* into the one FAQ node instead, so a deployed FAQPage and an FAQ block can
271	* never become two competing FAQPage entities.
272	*
273	* @since 1.32.0
274	* @param array $schema Schema array.
275	* @param string $type Schema @type.
276	* @param string $source Producer key from PRIMARY_PRECEDENCE.
277	* @return void
278	*/
279	public function add_primary(array $schema, string $type, string $source): void {
280	if (empty($schema)) {
281	return;
282	}
283
284	$type = $this->effective_type($schema, $type);
285
286	if ('FAQPage' === $type && $this->should_emit_faqpage()) {
287	$this->add_faq_entities($schema['mainEntity'] ?? []);
288	return;
289	}
290
291	// A third party owns the page's FAQPage, so ours must not be emitted
292	// (#494). Demote rather than drop: a FAQPage is still the page, and
293	// returning here would leave the URL with no page-level entity at all.
294	if ('FAQPage' === $type) {
295	$schema['@type'] = 'WebPage';
296	unset($schema['mainEntity']);
297	$type = 'WebPage';
298	}
299
300	// A per-post deployment can be something that isn't what the page is
301	// about (an Organization, say). Letting it win the slot would drop the
302	// page's real entity, so it joins the graph as a supporting node.
303	if (!in_array($type, self::PAGE_LEVEL_TYPES, true)) {
304	$this->supporting[] = $schema;
305	return;
306	}
307
308	$this->primary_candidates[] = [
309	'rank' => self::PRIMARY_PRECEDENCE[$source] ?? PHP_INT_MAX,
310	'schema' => $schema,
311	'type' => $type,
312	];
313	}
314
315	/**
316	* Resolve what a schema actually is, not what it was configured as.
317	*
318	* The two differ whenever a generator falls back — a post type configured
319	* as FAQPage emits a WebPage when the page has no genuine Q&A. Trusting the
320	* configured label there would route a WebPage into FAQ merging and drop it.
321	*
322	* @since 1.32.0
323	* @param array $schema Schema array.
324	* @param string $declared Type the producer declared.
325	* @return string
326	*/
327	private function effective_type(array $schema, string $declared): string {
328	$actual = $schema['@type'] ?? '';
329
330	return (is_string($actual) && $actual !== '') ? $actual : $declared;
331	}
332
333	/**
334	* Whether a page entity may carry a `breadcrumb` property.
335	*
336	* Reading the node's own `@type` key is not enough, and every case it
337	* misses ends with a real WebPage losing a valid property:
338	*
339	* - A deployed schema whose stored JSON omits `@type` carries the type in
340	* the `schema_type` column instead. `effective_type()` already resolves
341	* that, which is why the node's `@id` reads `#webpage` even though the
342	* node itself has no `@type` — so the resolved value is what has to be
343	* consulted here too.
344	* - JSON-LD permits several types on one node. `["WebPage", "FAQPage"]` is
345	* a WebPage, but a strict in_array() against the array as a whole is
346	* false, so the trail would be dropped from a page that may carry it.
347	* - A list naming nothing usable (`[]`, `[null]`) is the first case wearing
348	* the second's clothes, and resolves the same way.
349	*
350	* @since 2.7.0
351	* @param array $node The page entity.
352	* @param string $resolved_type Type the graph resolved for it.
353	* @return bool
354	*/
355	private function allows_breadcrumb(array $node, string $resolved_type): bool {
356	$declared = $node['@type'] ?? '';
357
358	// One path for both shapes. Splitting them invites the list branch to
359	// grow its own idea of what an absent type means, which is the mistake
360	// being corrected here in the first place.
361	$named = false;
362
363	foreach (is_array($declared) ? $declared : [$declared] as $type) {
364	if (!is_string($type) \|\| '' === $type) {
365	continue;
366	}
367
368	$named = true;
369
370	if (in_array($type, self::BREADCRUMB_TYPES, true)) {
371	return true;
372	}
373	}
374
375	// The node named a type, and none of them may carry a breadcrumb.
376	if ($named) {
377	return false;
378	}
379
380	// It named none, so it is whatever the graph resolved for it — the same
381	// value its @id was minted from. An empty list is no more informative
382	// than a missing key and must not read as "definitely not a WebPage".
383	return in_array($resolved_type, self::BREADCRUMB_TYPES, true);
384	}
385
386	/**
387	* Register a node that does not compete for the page-level slot.
388	*
389	* @since 1.32.0
390	* @param array $schema Schema array.
391	* @param string $type Schema @type.
392	* @return void
393	*/
394	public function add_supporting(array $schema, string $type): void {
395	if (empty($schema)) {
396	return;
397	}
398
399	$effective_type = $this->effective_type($schema, $type);
400
401	// A supporting FAQPage never survives as its own node: its questions
402	// merge into the graph's single FAQ node, or are dropped when a third
403	// party already owns the page's FAQPage (#494). Unlike the primary
404	// slot there is nothing to preserve here, so demotion would only add a
405	// second page-level entity beside the real one.
406	if ('FAQPage' === $effective_type) {
407	if ($this->should_emit_faqpage()) {
408	$this->add_faq_entities($schema['mainEntity'] ?? []);
409	}
410	return;
411	}
412
413	// One breadcrumb trail per page. A deployed BreadcrumbList lands here
414	// and output_breadcrumb_schema() adds a second on its own wp_head hook,
415	// so pages ended up with #breadcrumb and #breadcrumb-2 — two conflicting
416	// trails, with the primary node linking to only one of them (#471).
417	// First writer wins.
418	if ('BreadcrumbList' === $effective_type && $this->has_supporting_type('BreadcrumbList')) {
419	return;
420	}
421
422	$this->supporting[] = $schema;
423	}
424
425	/**
426	* Whether a supporting node of the given type has already been collected.
427	*
428	* @since 1.16.0
429	*
430	* @param string $type Schema type.
431	* @return bool
432	*/
433	private function has_supporting_type(string $type): bool {
434	foreach ($this->supporting as $node) {
435	if (($node['@type'] ?? '') === $type) {
436	return true;
437	}
438	}
439
440	return false;
441	}
442
443	/**
444	* Merge FAQ questions into the single FAQ node, deduped by question text.
445	*
446	* @since 1.32.0
447	* @param mixed $entities Candidate Question entities.
448	* @return void
449	*/
450	public function add_faq_entities($entities): void {
451	if (!is_array($entities)) {
452	return;
453	}
454
455	foreach ($entities as $entity) {
456	if (!is_array($entity)) {
457	continue;
458	}
459
460	$question = isset($entity['name']) ? trim((string) $entity['name']) : '';
461	$answer = isset($entity['acceptedAnswer']['text'])
462	? trim((string) $entity['acceptedAnswer']['text'])
463	: '';
464
465	if ($question === '' \|\| $answer === '') {
466	continue;
467	}
468
469	$key = strtolower(preg_replace('/\s+/', ' ', $question) ?? $question);
470
471	// First writer wins, so the deliberate per-post deployment keeps its
472	// wording when the same question also appears in a block.
473	if (!isset($this->faq_entities[$key])) {
474	$this->faq_entities[$key] = $entity;
475	}
476	}
477	}
478
479	/**
480	* Whether FAQ content from the post body has been absorbed into the graph.
481	*
482	* The FAQ block and Elementor widget call this to decide whether to skip
483	* their own inline JSON-LD. False (nothing absorbed, or the graph never ran)
484	* leaves their original behaviour untouched.
485	*
486	* @since 1.32.0
487	* @return bool
488	*/
489	public function absorbed_content_faq(): bool {
490	$this->maybe_collect_post_faq();
491
492	return $this->absorbed_content_faq;
493	}
494
495	/**
496	* Announce that this graph will be rendered on the current request.
497	*
498	* Called where the render hook is registered, so the graph can tell "I am
499	* about to be emitted" from "nothing will output me" without inspecting
500	* hooks it does not own.
501	*
502	* @since 1.32.0
503	* @return void
504	*/
505	public function schedule_render(): void {
506	$this->render_scheduled = true;
507	}
508
509	/**
510	* Collect the queried post's FAQ content if nothing has yet.
511	*
512	* Block themes render the whole template — post content included — from
513	* `get_the_block_template_html()`, and on some flows that happens before
514	* `wp_head` fires. The FAQ block therefore asked whether it had been
515	* absorbed while the graph's own collection pass was still pending, read
516	* false, and emitted a second FAQPage beside the graph's. Collecting on
517	* first ask makes the answer independent of which side runs first; the
518	* result is identical either way, because collection reads `post_content`
519	* rather than anything the render produces.
520	*
521	* @since 1.32.0
522	* @return void
523	*/
524	private function maybe_collect_post_faq(): void {
525	if ($this->faq_collected \|\| $this->rendered \|\| !$this->render_scheduled) {
526	return;
527	}
528
529	if (!function_exists('is_singular') \|\| !is_singular()) {
530	return;
531	}
532
533	$post = get_post();
534	if ($post instanceof \WP_Post) {
535	$this->collect_post_faq($post);
536	}
537	}
538
539	/**
540	* Pull FAQ content out of a post's blocks and Elementor data.
541	*
542	* Runs during wp_head, before the body renders, so the block and widget can
543	* see that their content is already accounted for.
544	*
545	* @since 1.32.0
546	* @param \WP_Post $post Post being viewed.
547	* @return void
548	*/
549	public function collect_post_faq(\WP_Post $post): void {
550	if ($this->faq_collected) {
551	return;
552	}
553
554	$this->faq_collected = true;
555
556	// Reading post_content directly bypasses the gate the render path gets
557	// for free: behind a password form the FAQ block never renders, so it
558	// never emitted schema. Without this check the graph would publish the
559	// questions and answers of protected content to anyone.
560	if (function_exists('post_password_required') && post_password_required($post)) {
561	return;
562	}
563
564	// The same gate, for the same reason, with a different cause: a Bricks
565	// page throws `post_content` away, so a FAQ block left there when the
566	// page was switched over never renders. Publishing its questions would
567	// put schema on the page for content no visitor can see — which Google
568	// treats as a violation, not merely a duplicate (#650).
569	if (!$this->bricks_supersedes_post_content((int) $post->ID)) {
570	$this->collect_block_faq($post);
571	}
572
573	$this->collect_elementor_faq($post);
574	$this->collect_bricks_faq($post);
575	$this->collect_beaver_faq($post);
576	}
577
578	/**
579	* Whether Bricks renders this post and discards its `post_content`.
580	*
581	* @since 2.3.1
582	* @param int $post_id Post being viewed.
583	* @return bool
584	*/
585	private function bricks_supersedes_post_content(int $post_id): bool {
586	if (!class_exists('ThinkRank\\SEO\\Builder_Content')) {
587	$file = THINKRANK_PLUGIN_DIR . 'includes/seo/class-builder-content.php';
588	if (!file_exists($file)) {
589	return false;
590	}
591	require_once $file;
592	}
593
594	return \ThinkRank\SEO\Builder_Content::bricks_supersedes_post_content($post_id);
595	}
596
597	/**
598	* Record that a body FAQ producer's content is represented in the graph.
599	*
600	* Deliberately not keyed on the entity count growing: when a block asks the
601	* same question as the per-post deployment, dedup means nothing is added,
602	* but the block's content is covered and it must still stay quiet.
603	*
604	* @since 1.32.0
605	* @param array $entities Questions found on that producer.
606	* @return void
607	*/
608	private function absorb_content_faq(array $entities): void {
609	if (empty($entities)) {
610	return;
611	}
612
613	$this->add_faq_entities($entities);
614	$this->absorbed_content_faq = true;
615	}
616
617	/**
618	* Collect FAQ questions from thinkrank/faq blocks, including nested ones.
619	*
620	* @since 1.32.0
621	* @param \WP_Post $post Post being viewed.
622	* @return void
623	*/
624	private function collect_block_faq(\WP_Post $post): void {
625	if (!function_exists('parse_blocks') \|\| !has_blocks($post->post_content)) {
626	return;
627	}
628
629	$this->walk_blocks(parse_blocks($post->post_content));
630	}
631
632	/**
633	* Recurse a parsed block tree collecting FAQ entries.
634	*
635	* @since 1.32.0
636	* @param array $blocks Parsed blocks.
637	* @return void
638	*/
639	private function walk_blocks(array $blocks): void {
640	foreach ($blocks as $block) {
641	if (!is_array($block)) {
642	continue;
643	}
644
645	if (($block['blockName'] ?? '') === self::FAQ_BLOCK) {
646	$attrs = $block['attrs'] ?? [];
647
648	// Mirrors Blocks_Manager: schema is on unless explicitly disabled.
649	$disabled = array_key_exists('outputSchema', $attrs) && false === $attrs['outputSchema'];
650
651	if (!$disabled) {
652	$this->absorb_content_faq($this->questions_from_pairs($attrs['faqs'] ?? []));
653	}
654	}
655
656	if (!empty($block['innerBlocks']) && is_array($block['innerBlocks'])) {
657	$this->walk_blocks($block['innerBlocks']);
658	}
659	}
660	}
661
662	/**
663	* Collect FAQ questions from Elementor FAQ widgets.
664	*
665	* @since 1.32.0
666	* @param \WP_Post $post Post being viewed.
667	* @return void
668	*/
669	private function collect_elementor_faq(\WP_Post $post): void {
670	$raw = get_post_meta($post->ID, '_elementor_data', true);
671	if (empty($raw) \|\| !is_string($raw)) {
672	return;
673	}
674
675	$elements = json_decode($raw, true);
676	if (!is_array($elements)) {
677	return;
678	}
679
680	$this->walk_elementor($elements);
681	}
682
683	/**
684	* Collect FAQ questions from Bricks FAQ elements.
685	*
686	* Reads the tree Bricks will actually render — resolved through
687	* `Builder_Content`, so a page whose content lives on a content template or
688	* inside a component is covered, and one switched back to the block editor
689	* is not.
690	*
691	* Unlike the block, this is not gated on Bricks owning `post_content`: a
692	* Bricks element is on the page whenever Bricks renders the page, which is
693	* exactly what resolving the tree already establishes (#626).
694	*
695	* @since 2.3.1
696	* @param \WP_Post $post Post being viewed.
697	* @return void
698	*/
699	private function collect_bricks_faq(\WP_Post $post): void {
700	$this->walk_bricks($this->bricks_tree((int) $post->ID));
701	}
702
703	/**
704	* Collect FAQ questions from Beaver Builder FAQ modules.
705	*
706	* Beaver Builder keeps its layout in postmeta as a map of node objects and
707	* leaves `post_content` alone, so — unlike Bricks — there is no
708	* "supersedes post_content" gate to apply: a block FAQ left in the body and
709	* a module FAQ in the layout can both genuinely be on the page, and both
710	* belong in the one FAQPage.
711	*
712	* The published layout is preferred over the draft for the same reason the
713	* rest of the plugin prefers it: a draft holds edits no visitor has been
714	* served yet, and schema must describe the page as delivered.
715	*
716	* @since 2.5.0
717	* @param \WP_Post $post Post being viewed.
718	* @return void
719	*/
720	private function collect_beaver_faq(\WP_Post $post): void {
721	$layout = get_post_meta($post->ID, '_fl_builder_data', true);
722
723	if (!is_array($layout) \|\| empty($layout)) {
724	return;
725	}
726
727	foreach ($layout as $node) {
728	$settings = is_object($node) ? ($node->settings ?? null) : ($node['settings'] ?? null);
729	$settings = is_object($settings) ? get_object_vars($settings) : $settings;
730
731	if (!is_array($settings) \|\| ($settings['type'] ?? '') !== self::FAQ_BEAVER_MODULE) {
732	continue;
733	}
734
735	// Mirrors ThinkRank_Beaver_FAQ_Module::schema_enabled(): Beaver
736	// Builder stores a cleared toggle as the string '0'.
737	if (empty($settings['output_schema'])) {
738	continue;
739	}
740
741	$rows = $settings['faqs'] ?? [];
742	$rows = is_array($rows) ? array_map(
743	static function ($row) {
744	return is_object($row) ? get_object_vars($row) : $row;
745	},
746	$rows
747	) : [];
748
749	$this->absorb_content_faq($this->questions_from_pairs($rows));
750	}
751	}
752
753	/**
754	* Collect FAQ entries from a resolved Bricks tree.
755	*
756	* The tree is flat, so no recursion: `Builder_Content::bricks_tree()`
757	* splices component definitions into the same list.
758	*
759	* The element's own settings are read here rather than through
760	* `FAQ_Element`, whose class extends `Bricks\Element` and so cannot even be
761	* loaded when the theme is inactive — which is exactly the case that still
762	* has a stored tree, on a site that has since switched themes. The repeater
763	* uses the same `question` / `answer` keys as the block, so the shared
764	* builder below already understands it.
765	*
766	* @since 2.3.1
767	* @param array $elements Bricks elements.
768	* @return void
769	*/
770	private function walk_bricks(array $elements): void {
771	foreach ($elements as $element) {
772	if (!is_array($element) \|\| ($element['name'] ?? '') !== self::FAQ_BRICKS_ELEMENT) {
773	continue;
774	}
775
776	$settings = is_array($element['settings'] ?? null) ? $element['settings'] : [];
777
778	// Mirrors FAQ_Element: a cleared Bricks checkbox loses its key.
779	if (empty($settings['outputSchema'])) {
780	continue;
781	}
782
783	$this->absorb_content_faq($this->questions_from_pairs($settings['faqs'] ?? []));
784	}
785	}
786
787	/**
788	* Recurse an Elementor element tree collecting FAQ entries.
789	*
790	* @since 1.32.0
791	* @param array $elements Elementor elements.
792	* @return void
793	*/
794	private function walk_elementor(array $elements): void {
795	foreach ($elements as $element) {
796	if (!is_array($element)) {
797	continue;
798	}
799
800	if (($element['widgetType'] ?? '') === self::FAQ_WIDGET) {
801	$settings = $element['settings'] ?? [];
802
803	// Mirrors FAQ_Widget: schema unless the toggle is off.
804	if ('yes' === ($settings['output_schema'] ?? 'yes')) {
805	$this->absorb_content_faq($this->questions_from_pairs($settings['faqs'] ?? []));
806	}
807	}
808
809	if (!empty($element['elements']) && is_array($element['elements'])) {
810	$this->walk_elementor($element['elements']);
811	}
812	}
813	}
814
815	/**
816	* Turn stored question/answer pairs into Question entities.
817	*
818	* @since 1.32.0
819	* @param mixed $pairs Repeater rows with question/answer keys.
820	* @return array
821	*/
822	private function questions_from_pairs($pairs): array {
823	if (!is_array($pairs)) {
824	return [];
825	}
826
827	$entities = [];
828
829	foreach ($pairs as $pair) {
830	if (!is_array($pair)) {
831	continue;
832	}
833
834	$question = isset($pair['question']) ? trim(wp_strip_all_tags((string) $pair['question'])) : '';
835	$answer = isset($pair['answer']) ? trim((string) $pair['answer']) : '';
836
837	if ($question === '' \|\| $answer === '') {
838	continue;
839	}
840
841	$text = wp_kses_post($answer);
842
843	// Mirrors Blocks_Manager::build_faq_schema() by calling the same
844	// builder, so the two paths cannot drift — the per-item image is
845	// resolved from its attachment id, carries intrinsic dimensions,
846	// and disappears if the media was deleted (#418).
847	$text .= \ThinkRank\Editor\Blocks_Manager::faq_image_markup(is_array($pair) ? $pair : []);
848
849	$entities[] = [
850	'@type' => 'Question',
851	'name' => $question,
852	'acceptedAnswer' => [
853	'@type' => 'Answer',
854	'text' => $text,
855	],
856	];
857	}
858
859	return $entities;
860	}
861
862	/**
863	* Whether anything has been registered.
864	*
865	* @since 1.32.0
866	* @return bool
867	*/
868	public function has_nodes(): bool {
869	return !empty($this->primary_candidates) \|\| !empty($this->supporting) \|\| !empty($this->faq_entities);
870	}
871
872	/**
873	* Whether ThinkRank may emit structured data for this request at all.
874	*
875	* The master switch and the matrix's per-content-type Schema switch, asked
876	* once. #461 put the master switch inside output_site_schema_markup(),
877	* which is one of four producers; the other three never learned about it,
878	* so turning Schema off removed the deployed rows and left the live
879	* generator running — the page emitted more types with the switch off
880	* than with it on (#688).
881	*
882	* Static because the producers that need it do not share a base class: the
883	* three graph producers converge on render(), but Blocks_Manager emits its
884	* own script tag from a content filter and never touches the graph, so it
885	* has to ask the same question independently.
886	*
887	* @since 2.7.0
888	* @return bool True when structured data may be emitted.
889	*/
890	public static function output_allowed(): bool {
891	// Memoised because inject_block_schema() asks once per matching block,
892	// and Schema_Management_System's constructor builds a schema builder and
893	// a cache manager and registers listeners — it is not something to spin
894	// up per block. The switch is site-wide, so it cannot change within a
895	// request; the per-content-type check below is query-dependent and stays
896	// live.
897	if (null === self::$master_switch_on) {
898	self::$master_switch_on = true;
899
900	if (class_exists('ThinkRank\\SEO\\Schema_Management_System')) {
901	$settings = (new \ThinkRank\SEO\Schema_Management_System())->get_settings('site', null);
902
903	// Absent means "not configured", which every other reader treats
904	// as enabled; only a value that is present and off disables.
905	self::$master_switch_on = !(array_key_exists('enabled', $settings) && empty($settings['enabled']));
906	}
907	}
908
909	if (!self::$master_switch_on) {
910	return false;
911	}
912
913	if (class_exists('ThinkRank\\SEO\\Content_Type_Settings')) {
914	return \ThinkRank\SEO\Content_Type_Settings::is_enabled_for_current(
915	\ThinkRank\SEO\Content_Type_Settings::FEATURE_SCHEMA,
916	true
917	);
918	}
919
920	return true;
921	}
922
923	/**
924	* Assemble and emit the graph. Safe to call more than once.
925	*
926	* @since 1.32.0
927	* @return void
928	*/
929	public function render(): void {
930	if ($this->rendered \|\| !$this->has_nodes()) {
931	return;
932	}
933
934	// Every graph producer converges here, so this is the one place the
935	// master switch has to hold for all of them (#688).
936	if (!self::output_allowed()) {
937	return;
938	}
939
940	// A 404 response represents no content, so there is nothing for
941	// structured data to describe. The page-level producers already skip
942	// this context, but the site-identity entity does not, so without this
943	// guard every miss — including crawlers probing URLs that never existed
944	// — emits a Person carrying email, telephone and birthDate (#481).
945	if (is_404()) {
946	return;
947	}
948
949	$this->rendered = true;
950
951	$graph = $this->build_graph();
952
953	/**
954	* Filter the assembled schema graph before output.
955	*
956	* Receives every node ThinkRank is about to emit, already deduped and
957	* linked, so add-ons can append or adjust nodes in one place.
958	*
959	* @since 1.32.0
960	*
961	* @param array $graph List of schema nodes ([] suppresses output).
962	*/
963	$graph = apply_filters('thinkrank_schema_graph', $graph);
964
965	// Drop empty properties across every node. An empty string is worse
966	// than an absent one — "headline": "" fails Article validation harder
967	// than omitting it — and Schema_Builder::clean_schema_array(), which was
968	// written for exactly this, is never reached from the render path
969	// (#471). Runs after the filter so add-on nodes are cleaned too.
970	$graph = array_values(array_filter(array_map([$this, 'prune_empty_values'], $graph)));
971
972	if (empty($graph)) {
973	return;
974	}
975
976	// One pass over the assembled graph, rather than at each producer.
977	// @id and url values arrive from a dozen of them — some derived from
978	// WordPress, some read straight out of stored settings — and on a
979	// misconfigured site that produced a single graph carrying both
980	// schemes at once, with @ids that no longer matched the canonical they
981	// are supposed to identify (#638). Normalizing where the graph is
982	// serialized is the only place that catches all of them, including
983	// nodes an add-on added through the filter above.
984	$graph = \ThinkRank\SEO\Url_Scheme::apply_deep($graph);
985
986	$json = wp_json_encode(
987	['@context' => self::SCHEMA_CONTEXT, '@graph' => array_values($graph)],
988	JSON_UNESCAPED_SLASHES \| JSON_UNESCAPED_UNICODE \| JSON_PRETTY_PRINT
989	\| JSON_HEX_TAG \| JSON_HEX_AMP \| JSON_HEX_APOS \| JSON_HEX_QUOT
990	);
991
992	if (false === $json) {
993	return;
994	}
995
996	echo "<!-- ThinkRank Schema Graph -->\n";
997	echo '<script type="application/ld+json">' . "\n";
998	echo $json . "\n"; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- wp_json_encode with JSON_HEX_* cannot break out of the script block.
999	echo '</script>' . "\n";
1000	echo "<!-- /ThinkRank Schema Graph -->\n";
1001	}
1002
1003	/**
1004	* Replace an inline entity with an @id reference to an equivalent node.
1005	*
1006	* Matches on name so a post author is never silently collapsed into the
1007	* site's Person entity, and vice versa (#471).
1008	*
1009	* @since 1.16.0
1010	*
1011	* @param mixed $inline The inline entity from the primary node.
1012	* @param array $candidates Nodes already in the graph, each with an @id.
1013	* @return array\|null ['@id' => …] when a match is found, null otherwise.
1014	*/
1015	private function link_to_node($inline, array $candidates): ?array {
1016	if (!is_array($inline) \|\| empty($candidates)) {
1017	return null;
1018	}
1019
1020	// Already a reference.
1021	if (isset($inline['@id']) && !isset($inline['name'])) {
1022	return null;
1023	}
1024
1025	$inline_name = isset($inline['name']) ? trim((string) $inline['name']) : '';
1026
1027	if ('' === $inline_name) {
1028	return null;
1029	}
1030
1031	foreach ($candidates as $candidate) {
1032	$candidate_name = isset($candidate['name']) ? trim((string) $candidate['name']) : '';
1033
1034	if ('' !== $candidate_name
1035	&& 0 === strcasecmp($candidate_name, $inline_name)
1036	&& !empty($candidate['@id'])
1037	) {
1038	return ['@id' => $candidate['@id']];
1039	}
1040	}
1041
1042	return null;
1043	}
1044
1045	/**
1046	* Recursively drop empty properties from a schema node.
1047	*
1048	* Removes '', [], and null. Deliberately keeps numeric 0, boolean false and
1049	* the structural keys, which are all meaningful values.
1050	*
1051	* @since 1.16.0
1052	*
1053	* @param mixed $value Node or property value.
1054	* @return mixed Cleaned value.
1055	*/
1056	private function prune_empty_values($value) {
1057	if (!is_array($value)) {
1058	return $value;
1059	}
1060
1061	$cleaned = [];
1062
1063	foreach ($value as $key => $item) {
1064	// Never prune the keys that give a node its identity.
1065	if (in_array($key, ['@context', '@type', '@id'], true)) {
1066	$cleaned[$key] = $item;
1067	continue;
1068	}
1069
1070	if (is_array($item)) {
1071	$item = $this->prune_empty_values($item);
1072
1073	if ([] === $item) {
1074	continue;
1075	}
1076
1077	$cleaned[$key] = $item;
1078	continue;
1079	}
1080
1081	if (null === $item \|\| '' === $item) {
1082	continue;
1083	}
1084
1085	$cleaned[$key] = $item;
1086	}
1087
1088	return $cleaned;
1089	}
1090
1091	/**
1092	* Build the linked node list.
1093	*
1094	* @since 1.32.0
1095	* @return array
1096	*/
1097	private function build_graph(): array {
1098	$selection = $this->select_primary_set();
1099	$primary = $selection['winner'];
1100	$siblings = $selection['siblings'];
1101	$faq = $this->build_faq_node();
1102	$base = $this->base_url($primary);
1103
1104	// With no other page-level entity, the FAQ node is the page.
1105	if (null === $primary && null !== $faq) {
1106	$primary = ['schema' => $faq, 'type' => 'FAQPage'];
1107	$faq = null;
1108	}
1109
1110	$nodes = [];
1111	$primary_id = '';
1112	$primary_type = '';
1113	$used_ids = [];
1114
1115	if (null !== $primary) {
1116	$node = $primary['schema'];
1117
1118	// Key the @id off the node's resolved @type, not the configured one,
1119	// so an "Article" setting that renders BlogPosting reads #blogposting.
1120	$resolved_type = $this->effective_type($node, $primary['type']);
1121
1122	$node = $this->assign_id($node, $base . '#' . strtolower($resolved_type), $used_ids);
1123	$primary_id = $node['@id'];
1124	$primary_type = $resolved_type;
1125	$nodes['primary'] = $node;
1126	}
1127
1128	// Entities deployed alongside the winner (Pro's Multi-Schema lets a post
1129	// carry an Article and a Recipe). They lost the page slot but were
1130	// deliberately deployed, so they stay in the graph linked to the primary
1131	// rather than being dropped.
1132	foreach ($siblings as $index => $sibling) {
1133	$node = $sibling['schema'];
1134
1135	$node = $this->assign_id(
1136	$node,
1137	$base . '#' . strtolower($this->effective_type($node, $sibling['type'])),
1138	$used_ids
1139	);
1140
1141	if ($primary_id !== '' && $node['@id'] !== $primary_id) {
1142	$node['isPartOf'] = $node['isPartOf'] ?? ['@id' => $primary_id];
1143	$node['mainEntityOfPage'] = $node['mainEntityOfPage'] ?? ['@id' => $primary_id];
1144	}
1145
1146	$nodes['sibling_' . $index] = $node;
1147	}
1148
1149	if (null !== $faq) {
1150	$faq = $this->assign_id($faq, $base . '#faq', $used_ids);
1151
1152	if ($primary_id !== '') {
1153	$faq['isPartOf'] = ['@id' => $primary_id];
1154	$faq['mainEntityOfPage'] = ['@id' => $primary_id];
1155	}
1156
1157	$nodes['faq'] = $faq;
1158	}
1159
1160	$website_id = '';
1161	$breadcrumb_id = '';
1162	$organization_nodes = [];
1163	$person_nodes = [];
1164
1165	foreach ($this->supporting as $index => $node) {
1166	$type = $node['@type'] ?? '';
1167
1168	if ('BreadcrumbList' === $type) {
1169	$node = $this->assign_id($node, $base . '#breadcrumb', $used_ids);
1170	$breadcrumb_id = $node['@id'];
1171	} elseif ('WebSite' === $type) {
1172	$node = $this->assign_id($node, home_url('/#website'), $used_ids);
1173	$website_id = $node['@id'];
1174	} elseif ('Organization' === $type) {
1175	$node = $this->assign_id($node, home_url('/#organization'), $used_ids);
1176	$organization_nodes[] = $node;
1177	} elseif (in_array($type, self::SITE_LEVEL_TYPES, true)) {
1178	// Site-level entities describe the site, not the page, so their
1179	// @id must be stable across URLs. Falling through to the
1180	// page-scoped branch minted a fresh identity on every URL, so
1181	// one business became N entities in a crawler's graph and
1182	// nothing could reference it by @id (#471).
1183	// One entity, emitted once. The site identity and a per-post
1184	// deployment describe the same person or business, so both
1185	// arrive here claiming the same @id. assign_id() would resolve
1186	// that collision by minting "#person-2", turning a duplicate
1187	// into two competing entities that split the identity a
1188	// knowledge graph is meant to consolidate (#479).
1189	$duplicate_key = $this->find_same_entity($nodes, $type, $node);
1190
1191	if (null !== $duplicate_key) {
1192	$nodes[$duplicate_key] = $this->merge_entity($nodes[$duplicate_key], $node);
1193	continue;
1194	}
1195
1196	$node = $this->assign_id($node, home_url('/#' . strtolower($type)), $used_ids);
1197
1198	if ('Person' === $type) {
1199	$person_nodes[] = $node;
1200	}
1201	} elseif (is_string($type) && $type !== '') {
1202	$node = $this->assign_id($node, $base . '#' . strtolower($type), $used_ids);
1203	}
1204
1205	$nodes['supporting_' . $index] = $node;
1206	}
1207
1208	// Link the page entity to the site and its breadcrumb trail.
1209	if (isset($nodes['primary'])) {
1210	if ($website_id !== '' && !isset($nodes['primary']['isPartOf'])) {
1211	$nodes['primary']['isPartOf'] = ['@id' => $website_id];
1212	}
1213	if (
1214	$breadcrumb_id !== ''
1215	&& !isset($nodes['primary']['breadcrumb'])
1216	&& $this->allows_breadcrumb($nodes['primary'], $primary_type)
1217	) {
1218	$nodes['primary']['breadcrumb'] = ['@id' => $breadcrumb_id];
1219	}
1220
1221	// Point publisher/author at the full nodes already in the graph.
1222	// They were emitted inline with no @id, so the graph described the
1223	// same publisher twice — and the richer node, the one carrying the
1224	// logo Google needs for Article, was not the one publisher
1225	// referenced (#471).
1226	//
1227	// Only collapse when the inline object names the SAME entity. A post
1228	// author and the site's Person entity are frequently different
1229	// people, so matching on position rather than identity would
1230	// misattribute authorship.
1231	if (isset($nodes['primary']['publisher'])) {
1232	$linked = $this->link_to_node($nodes['primary']['publisher'], $organization_nodes);
1233	if (null !== $linked) {
1234	$nodes['primary']['publisher'] = $linked;
1235	}
1236	}
1237
1238	if (isset($nodes['primary']['author'])) {
1239	$linked = $this->link_to_node($nodes['primary']['author'], $person_nodes);
1240	if (null !== $linked) {
1241	$nodes['primary']['author'] = $linked;
1242	}
1243	}
1244	}
1245
1246	// The graph carries @context once; per-node copies are redundant.
1247	foreach ($nodes as $key => $node) {
1248	unset($node['@context']);
1249	$nodes[$key] = $node;
1250	}
1251
1252	return array_values($nodes);
1253	}
1254
1255	/**
1256	* Pick the page-level entity, plus any deployed alongside it.
1257	*
1258	* Precedence arbitrates between sources, not between entities: a per-post
1259	* deployment beats the post-type-wide default, and the losing source is
1260	* dropped so one URL stops claiming to be several unrelated things (#355).
1261	*
1262	* Within the winning source every entity is kept. Deploying more than one
1263	* page-level schema on a post is exactly what Pro's Multi-Schema feature
1264	* exists to do (an Article that is also a Recipe), and silently discarding
1265	* the extras would delete markup the user deliberately published.
1266	*
1267	* @since 1.32.0
1268	* @return array{winner: array\|null, siblings: array<int,array>}
1269	*/
1270	private function select_primary_set(): array {
1271	if (empty($this->primary_candidates)) {
1272	return ['winner' => null, 'siblings' => []];
1273	}
1274
1275	$best = PHP_INT_MAX;
1276	foreach ($this->primary_candidates as $candidate) {
1277	if ($candidate['rank'] < $best) {
1278	$best = $candidate['rank'];
1279	}
1280	}
1281
1282	$kept = [];
1283	foreach ($this->primary_candidates as $candidate) {
1284	if ($candidate['rank'] === $best) {
1285	$kept[] = $candidate;
1286	}
1287	}
1288
1289	return ['winner' => array_shift($kept), 'siblings' => array_values($kept)];
1290	}
1291
1292	/**
1293	* Find an already-placed node describing the same entity as $node.
1294	*
1295	* Identity is `email` when both carry one — two people can share a name,
1296	* but not a mailbox — and a case-insensitive `name` match otherwise. A node
1297	* with neither never matches, so an unidentifiable entity is kept rather
1298	* than folded into an unrelated one.
1299	*
1300	* @since 2.0.2
1301	*
1302	* @param array $nodes Nodes placed so far, keyed.
1303	* @param string $type Schema type to match within.
1304	* @param array $node Candidate node.
1305	* @return string\|null Key of the matching node, or null.
1306	*/
1307	private function find_same_entity(array $nodes, string $type, array $node): ?string {
1308	$email = isset($node['email']) ? strtolower(trim((string) $node['email'])) : '';
1309	$name = isset($node['name']) ? trim((string) $node['name']) : '';
1310
1311	if ('' === $email && '' === $name) {
1312	return null;
1313	}
1314
1315	foreach ($nodes as $key => $placed) {
1316	if (($placed['@type'] ?? '') !== $type) {
1317	continue;
1318	}
1319
1320	$placed_email = isset($placed['email']) ? strtolower(trim((string) $placed['email'])) : '';
1321
1322	if ('' !== $email && '' !== $placed_email) {
1323	if ($email === $placed_email) {
1324	return (string) $key;
1325	}
1326	continue;
1327	}
1328
1329	$placed_name = isset($placed['name']) ? trim((string) $placed['name']) : '';
1330
1331	if ('' !== $name && '' !== $placed_name && 0 === strcasecmp($name, $placed_name)) {
1332	return (string) $key;
1333	}
1334	}
1335
1336	return null;
1337	}
1338
1339	/**
1340	* Fold a duplicate entity into the node already in the graph.
1341	*
1342	* Fills gaps only: a property the placed node already carries wins, so the
1343	* node that claimed the identity first keeps it, @id included. The
1344	* duplicate can still contribute properties the first copy lacked, which is
1345	* the point — between them they describe the entity more completely than
1346	* either does alone.
1347	*
1348	* @since 2.0.2
1349	*
1350	* @param array $placed Node already in the graph.
1351	* @param array $duplicate Node describing the same entity.
1352	* @return array Merged node.
1353	*/
1354	private function merge_entity(array $placed, array $duplicate): array {
1355	foreach ($duplicate as $key => $value) {
1356	if ('@id' === $key \|\| '@type' === $key \|\| '@context' === $key) {
1357	continue;
1358	}
1359
1360	if (!isset($placed[$key]) \|\| '' === $placed[$key] \|\| [] === $placed[$key]) {
1361	$placed[$key] = $value;
1362	}
1363	}
1364
1365	return $placed;
1366	}
1367
1368	/**
1369	* Give a node a unique @id, keeping one it already carries.
1370	*
1371	* Two entities of the same type on one page (two deployed Articles, say)
1372	* would otherwise mint the same @id, which makes the graph ambiguous about
1373	* which node a reference points at.
1374	*
1375	* @since 1.32.0
1376	* @param array $node Node to stamp.
1377	* @param string $fallback @id to use when the node has none.
1378	* @param array $used Already-issued @id values, updated by reference.
1379	* @return array
1380	*/
1381	private function assign_id(array $node, string $fallback, array &$used): array {
1382	$id = (isset($node['@id']) && is_string($node['@id']) && $node['@id'] !== '')
1383	? $node['@id']
1384	: $fallback;
1385
1386	if (isset($used[$id])) {
1387	$suffix = 2;
1388	while (isset($used[$id . '-' . $suffix])) {
1389	$suffix++;
1390	}
1391	$id .= '-' . $suffix;
1392	}
1393
1394	$used[$id] = true;
1395	$node['@id'] = $id;
1396
1397	return $node;
1398	}
1399
1400	/**
1401	* Whether ThinkRank should emit a FAQPage on this request.
1402	*
1403	* ThinkRank emitted its FAQPage unconditionally, so a URL whose FAQ was
1404	* already published by another plugin carried two FAQPage entities — each
1405	* valid on its own, together ambiguous about which one describes the page
1406	* (#494).
1407	*
1408	* The answer cannot be read off the rendered page. Third-party FAQ schema
1409	* is typically printed in `wp_footer` from data its widget only gathers
1410	* while the body renders, which is long after this graph goes out in
1411	* `wp_head`; at the moment of the decision the foreign FAQPage does not
1412	* exist yet, in the buffer or anywhere else. Detection therefore inspects
1413	* the stored post content, the same way collect_elementor_faq() finds
1414	* ThinkRank's own widget.
1415	*
1416	* @since 2.1.0
1417	* @return bool
1418	*/
1419	private function should_emit_faqpage(): bool {
1420	if (null !== $this->emit_faqpage) {
1421	return $this->emit_faqpage;
1422	}
1423
1424	$post = (function_exists('is_singular') && is_singular()) ? get_post() : null;
1425	if (!$post instanceof \WP_Post) {
1426	$post = null;
1427	}
1428
1429	$emit = !$this->has_foreign_faq_source($post);
1430
1431	/**
1432	* Filter whether ThinkRank emits its FAQPage entity.
1433	*
1434	* Return false from a plugin that publishes its own FAQPage on the same
1435	* URL and ThinkRank drops its FAQ node, leaving the page one
1436	* unambiguous FAQPage. ThinkRank already defaults this to false for the
1437	* FAQ sources it recognises, so the filter is for the ones it does not
1438	* — or for forcing its FAQPage back on.
1439	*
1440	* @since 2.1.0
1441	*
1442	* @param bool $emit Whether to emit the FAQPage node.
1443	* @param \WP_Post\|null $post Post being viewed, or null when not singular.
1444	*/
1445	$this->emit_faqpage = (bool) apply_filters('thinkrank_emit_faqpage', $emit, $post);
1446
1447	return $this->emit_faqpage;
1448	}
1449
1450	/**
1451	* Whether another plugin publishes a FAQPage for this post.
1452	*
1453	* @since 2.1.0
1454	* @param \WP_Post\|null $post Post being viewed.
1455	* @return bool
1456	*/
1457	private function has_foreign_faq_source(?\WP_Post $post): bool {
1458	if (!$post instanceof \WP_Post) {
1459	return false;
1460	}
1461
1462	return $this->has_foreign_elementor_faq($post) \|\| $this->has_foreign_bricks_faq($post);
1463	}
1464
1465	/**
1466	* Whether an Elementor widget on this post publishes a FAQPage.
1467	*
1468	* @since 2.1.0
1469	* @param \WP_Post $post Post being viewed.
1470	* @return bool
1471	*/
1472	private function has_foreign_elementor_faq(\WP_Post $post): bool {
1473	$raw = get_post_meta($post->ID, '_elementor_data', true);
1474	if (empty($raw) \|\| !is_string($raw)) {
1475	return false;
1476	}
1477
1478	$elements = json_decode($raw, true);
1479
1480	return is_array($elements) && $this->elements_have_foreign_faq($elements);
1481	}
1482
1483	/**
1484	* Whether a Bricks element on this post publishes a FAQPage.
1485	*
1486	* Bricks' accordions emit their FAQPage from the body render, so — exactly
1487	* as with EA's accordion — the stored tree is the only signal available at
1488	* `wp_head`, where this decision has to be made.
1489	*
1490	* The tree comes from Builder_Content rather than a direct meta read: a
1491	* Bricks page's content can live on a content template, be assembled from
1492	* components, or be stored but not rendered because the post was switched
1493	* back to the block editor. Reading the meta key here would get all three
1494	* wrong (#649).
1495	*
1496	* @since 2.3.1
1497	* @param \WP_Post $post Post being viewed.
1498	* @return bool
1499	*/
1500	private function has_foreign_bricks_faq(\WP_Post $post): bool {
1501	foreach ($this->bricks_tree((int) $post->ID) as $element) {
1502	if (is_array($element) && $this->bricks_element_publishes_faq($element)) {
1503	return true;
1504	}
1505	}
1506
1507	return false;
1508	}
1509
1510	/**
1511	* Whether one Bricks element will put a FAQPage on the page.
1512	*
1513	* Mirrors Bricks' own emission condition rather than trusting the toggle:
1514	* `accordion` records a question only for an item that has BOTH a title and
1515	* content, so an armed but empty accordion publishes nothing and must not
1516	* cost the page ThinkRank's FAQ node. `accordion-nested` builds its items
1517	* from child elements instead of a repeater, so having children is the
1518	* equivalent test there.
1519	*
1520	* @since 2.3.1
1521	* @param array $element One Bricks element.
1522	* @return bool
1523	*/
1524	private function bricks_element_publishes_faq(array $element): bool {
1525	$name = is_string($element['name'] ?? null) ? $element['name'] : '';
1526	if (!in_array($name, self::FOREIGN_FAQ_BRICKS_ELEMENTS, true)) {
1527	return false;
1528	}
1529
1530	$settings = is_array($element['settings'] ?? null) ? $element['settings'] : [];
1531
1532	// Bricks writes a checkbox as `true`, and clears it by removing the key.
1533	if (empty($settings['faqSchema'])) {
1534	return false;
1535	}
1536
1537	if ('accordion-nested' === $name) {
1538	return !empty($element['children']) && is_array($element['children']);
1539	}
1540
1541	$items = is_array($settings['accordions'] ?? null) ? $settings['accordions'] : [];
1542
1543	foreach ($items as $item) {
1544	if (is_array($item)
1545	&& '' !== trim((string) ($item['title'] ?? ''))
1546	&& '' !== trim((string) ($item['content'] ?? ''))
1547	) {
1548	return true;
1549	}
1550	}
1551
1552	return false;
1553	}
1554
1555	/**
1556	* The Bricks element tree that renders for a post.
1557	*
1558	* @since 2.3.1
1559	* @param int $post_id Post being viewed.
1560	* @return array<int,mixed>
1561	*/
1562	private function bricks_tree(int $post_id): array {
1563	if (!class_exists('ThinkRank\\SEO\\Builder_Content')) {
1564	$file = THINKRANK_PLUGIN_DIR . 'includes/seo/class-builder-content.php';
1565	if (!file_exists($file)) {
1566	return [];
1567	}
1568	require_once $file;
1569	}
1570
1571	return \ThinkRank\SEO\Builder_Content::bricks_tree($post_id);
1572	}
1573
1574	/**
1575	* Recurse an Elementor element tree looking for a third-party FAQ producer.
1576	*
1577	* @since 2.1.0
1578	* @param array $elements Elementor elements.
1579	* @return bool
1580	*/
1581	private function elements_have_foreign_faq(array $elements): bool {
1582	foreach ($elements as $element) {
1583	if (!is_array($element)) {
1584	continue;
1585	}
1586
1587	// Stored JSON, so nothing guarantees the shape: a non-string
1588	// widgetType would be an illegal array offset, not a miss.
1589	$widget = is_string($element['widgetType'] ?? null) ? $element['widgetType'] : '';
1590	$gate = self::FOREIGN_FAQ_WIDGETS[$widget] ?? '';
1591	$settings = is_array($element['settings'] ?? null) ? $element['settings'] : [];
1592
1593	if ($gate !== '' && 'yes' === ($settings[$gate] ?? '')) {
1594	return true;
1595	}
1596
1597	if (!empty($element['elements']) && is_array($element['elements'])
1598	&& $this->elements_have_foreign_faq($element['elements'])) {
1599	return true;
1600	}
1601	}
1602
1603	return false;
1604	}
1605
1606	/**
1607	* Build the single FAQ node, if any questions were collected.
1608	*
1609	* Gated on should_emit_faqpage(): every FAQ source in the plugin — the
1610	* block, the Elementor widget, a deployed row and the post-type default —
1611	* funnels through here, so this is the one place that can hold the whole
1612	* plugin's FAQPage back (#494).
1613	*
1614	* @since 1.32.0
1615	* @return array\|null
1616	*/
1617	private function build_faq_node(): ?array {
1618	if (empty($this->faq_entities) \|\| !$this->should_emit_faqpage()) {
1619	return null;
1620	}
1621
1622	return [
1623	'@type' => 'FAQPage',
1624	'mainEntity' => array_values($this->faq_entities),
1625	];
1626	}
1627
1628	/**
1629	* Base URL for @id values.
1630	*
1631	* @since 1.32.0
1632	* @return string
1633	*/
1634	private function base_url(?array $primary): string {
1635	if (is_singular()) {
1636	$permalink = get_permalink();
1637	if (is_string($permalink) && $permalink !== '') {
1638	return $permalink;
1639	}
1640	}
1641
1642	// Archives are not singular, so fall back to the URL the page entity
1643	// already resolved for itself. Without this every archive would mint the
1644	// same "<home>#collectionpage" @id and two categories would collide.
1645	$url = $primary['schema']['url'] ?? null;
1646	if (is_string($url) && $url !== '') {
1647	return $url;
1648	}
1649
1650	return home_url('/');
1651	}
1652	}
1653