← All changes | includes/frontend/class-schema-graph.php +581 -16 2.0.2 → 2.7.0 View file →

		@@ -87,8 +87,26 @@
87	87	'Book', 'Movie', 'Service', 'ImageObject', 'VideoObject',
88	88	];
89	89
90	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	+ /**
91	109	* Gutenberg FAQ block name.
92	110	*/
93	111	private const FAQ_BLOCK = 'thinkrank/faq';
94	112
		@@ -97,8 +115,53 @@
97	115	*/
98	116	private const FAQ_WIDGET = 'thinkrank-faq';
99	117
100	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	+ /**
101	164	* Singleton instance.
102	165	*
103	166	* @var self|null
104	167	*/
		@@ -104,8 +167,16 @@
104	167	*/
105	168	private static ?self $instance = null;
106	169
107	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	+ /**
108	179	* Competing page-level entities: ['rank' => int, 'schema' => array, 'type' => string].
109	180	*
110	181	* @var array<int,array>
111	182	*/
		@@ -125,8 +196,16 @@
125	196	*/
126	197	private array $faq_entities = [];
127	198
128	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	+ /**
129	208	* Whether FAQ content was taken from the rendered post body (block/widget),
130	209	* meaning those producers must not emit their own duplicate script.
131	210	*
132	211	* @var bool
		@@ -179,8 +258,10 @@
179	258	* @return void
180	259	*/
181	260	public static function reset(): void {
182	261	self::$instance = null;
	262	+ // Or a test that seeds the switch inherits the previous test's answer.
	263	+ self::$master_switch_on = null;
183	264	}
184	265
185	266	/**
186	267	* Register a candidate for the page's single page-level entity.
		@@ -201,13 +282,22 @@
201	282	}
202	283
203	284	$type = $this->effective_type($schema, $type);
204	285
205		- if ('FAQPage' === $type) {
	286	+ if ('FAQPage' === $type && $this->should_emit_faqpage()) {
206	287	$this->add_faq_entities($schema['mainEntity'] ?? []);
207	288	return;
208	289	}
209	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	+
210	300	// A per-post deployment can be something that isn't what the page is
211	301	// about (an Organization, say). Letting it win the slot would drop the
212	302	// page's real entity, so it joins the graph as a supporting node.
213	303	if (!in_array($type, self::PAGE_LEVEL_TYPES, true)) {
		@@ -240,8 +330,61 @@
240	330	return (is_string($actual) && $actual !== '') ? $actual : $declared;
241	331	}
242	332
243	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	+ /**
244	387	* Register a node that does not compete for the page-level slot.
245	388	*
246	389	* @since 1.32.0
247	390	* @param array $schema Schema array.
		@@ -254,10 +397,17 @@
254	397	}
255	398
256	399	$effective_type = $this->effective_type($schema, $type);
257	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.
258	406	if ('FAQPage' === $effective_type) {
259		- $this->add_faq_entities($schema['mainEntity'] ?? []);
	407	+ if ($this->should_emit_faqpage()) {
	408	+ $this->add_faq_entities($schema['mainEntity'] ?? []);
	409	+ }
260	410	return;
261	411	}
262	412
263	413	// One breadcrumb trail per page. A deployed BreadcrumbList lands here
		@@ -410,13 +560,42 @@
410	560	if (function_exists('post_password_required') && post_password_required($post)) {
411	561	return;
412	562	}
413	563
414		- $this->collect_block_faq($post);
	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	+
415	573	$this->collect_elementor_faq($post);
	574	+ $this->collect_bricks_faq($post);
	575	+ $this->collect_beaver_faq($post);
416	576	}
417	577
418	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	+ /**
419	598	* Record that a body FAQ producer's content is represented in the graph.
420	599	*
421	600	* Deliberately not keyed on the entity count growing: when a block asks the
422	601	* same question as the per-post deployment, dedup means nothing is added,
		@@ -501,8 +680,112 @@
501	680	$this->walk_elementor($elements);
502	681	}
503	682
504	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	+ /**
505	788	* Recurse an Elementor element tree collecting FAQ entries.
506	789	*
507	790	* @since 1.32.0
508	791	* @param array $elements Elementor elements.
		@@ -556,15 +839,13 @@
556	839	}
557	840
558	841	$text = wp_kses_post($answer);
559	842
560		- // Mirrors Blocks_Manager::build_faq_schema(): a per-item image is
561		- // carried inside the answer HTML (Yoast-style).
562		- $image_url = isset($pair['imageUrl']) ? esc_url((string) $pair['imageUrl']) : '';
563		- if ($image_url !== '') {
564		- $image_alt = isset($pair['imageAlt']) ? esc_attr((string) $pair['imageAlt']) : '';
565		- $text .= ' <img src="' . $image_url . '" alt="' . $image_alt . '" />';
566		- }
	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 : []);
567	848
568	849	$entities[] = [
569	850	'@type' => 'Question',
570	851	'name' => $question,
		@@ -588,8 +869,59 @@
588	869	return !empty($this->primary_candidates) || !empty($this->supporting) || !empty($this->faq_entities);
589	870	}
590	871
591	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	+ /**
592	924	* Assemble and emit the graph. Safe to call more than once.
593	925	*
594	926	* @since 1.32.0
595	927	* @return void
		@@ -598,8 +930,14 @@
598	930	if ($this->rendered || !$this->has_nodes()) {
599	931	return;
600	932	}
601	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	+
602	940	// A 404 response represents no content, so there is nothing for
603	941	// structured data to describe. The page-level producers already skip
604	942	// this context, but the site-identity entity does not, so without this
605	943	// guard every miss — including crawlers probing URLs that never existed
		@@ -634,8 +972,18 @@
634	972	if (empty($graph)) {
635	973	return;
636	974	}
637	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	+
638	986	$json = wp_json_encode(
639	987	['@context' => self::SCHEMA_CONTEXT, '@graph' => array_values($graph)],
640	988	JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT
641	989	| JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT
		@@ -758,11 +1106,12 @@
758	1106	$primary = ['schema' => $faq, 'type' => 'FAQPage'];
759	1107	$faq = null;
760	1108	}
761	1109
762		- $nodes = [];
763		- $primary_id = '';
764		- $used_ids = [];
	1110	+ $nodes = [];
	1111	+ $primary_id = '';
	1112	+ $primary_type = '';
	1113	+ $used_ids = [];
765	1114
766	1115	if (null !== $primary) {
767	1116	$node = $primary['schema'];
768	1117
		@@ -770,9 +1119,10 @@
770	1119	// so an "Article" setting that renders BlogPosting reads #blogposting.
771	1120	$resolved_type = $this->effective_type($node, $primary['type']);
772	1121
773	1122	$node = $this->assign_id($node, $base . '#' . strtolower($resolved_type), $used_ids);
774		- $primary_id = $node['@id'];
	1123	+ $primary_id = $node['@id'];
	1124	+ $primary_type = $resolved_type;
775	1125	$nodes['primary'] = $node;
776	1126	}
777	1127
778	1128	// Entities deployed alongside the winner (Pro's Multi-Schema lets a post
		@@ -859,9 +1209,13 @@
859	1209	if (isset($nodes['primary'])) {
860	1210	if ($website_id !== '' && !isset($nodes['primary']['isPartOf'])) {
861	1211	$nodes['primary']['isPartOf'] = ['@id' => $website_id];
862	1212	}
863		- if ($breadcrumb_id !== '' && !isset($nodes['primary']['breadcrumb'])) {
	1213	+ if (
	1214	+ $breadcrumb_id !== ''
	1215	+ && !isset($nodes['primary']['breadcrumb'])
	1216	+ && $this->allows_breadcrumb($nodes['primary'], $primary_type)
	1217	+ ) {
864	1218	$nodes['primary']['breadcrumb'] = ['@id' => $breadcrumb_id];
865	1219	}
866	1220
867	1221	// Point publisher/author at the full nodes already in the graph.
		@@ -1043,15 +1397,226 @@
1043	1397	return $node;
1044	1398	}
1045	1399
1046	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	+ /**
1047	1607	* Build the single FAQ node, if any questions were collected.
1048	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	+ *
1049	1614	* @since 1.32.0
1050	1615	* @return array|null
1051	1616	*/
1052	1617	private function build_faq_node(): ?array {
1053		- if (empty($this->faq_entities)) {
	1618	+ if (empty($this->faq_entities) || !$this->should_emit_faqpage()) {
1054	1619	return null;
1055	1620	}
1056	1621
1057	1622	return [