thinkrank / includes / abilities / content / class-get-faq.php

class-get-faq.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 2.14.0, at includes/abilities/content/class-get-faq.php

164 lines 6.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Get FAQ ability.
4	*
5	* @package ThinkRank\Abilities\Content
6	*/
7
8	declare(strict_types=1);
9
10	namespace ThinkRank\Abilities\Content;
11
12	use ThinkRank\Frontend\Schema_Graph;
13	use ThinkRank\SEO\FAQ_Content;
14
15	if ( ! defined( 'ABSPATH' ) ) {
16	exit; // Exit if accessed directly.
17	}
18
19	/**
20	* Reports the FAQ questions on one post, and whether they reach search engines.
21	*
22	* Three separate facts, because they come apart in practice and an agent that
23	* conflates them gives bad advice: the questions that are on the page, which
24	* editor surface holds them (only the block can be written back), and whether
25	* ThinkRank is actually publishing a FAQPage for the post. The third can be
26	* false while the first two are healthy, because the content type has Schema
27	* switched off, or because another plugin on the page already publishes its own
28	* FAQPage and ThinkRank stands down rather than emit a second one.
29	*
30	* `builder` answers which surface, and it has to be able to say more than
31	* "none". Oxygen reported as `none`, which is also what the block editor
32	* reports, so the post came back writable and an agent following that at face
33	* value had `update-faq` store a block Oxygen never renders (#831). Oxygen and
34	* Breakdance are now named, their own accordions are read in place of the FAQ
35	* module they do not have, and `writable_reason` plus `questions_readable` keep
36	* "cannot be written" apart from "cannot be read" — a post can be the first
37	* without being the second.
38	*/
39	class Get_FAQ extends FAQ_Ability_Base {
40
41	/**
42	* Constructor.
43	*/
44	public function __construct() {
45	$this->id = 'thinkrank/get-faq';
46	$this->label = __( 'Get ThinkRank FAQ', 'thinkrank' );
47	$this->description = __( 'Read the FAQ questions and answers on one post, where they are stored (the ThinkRank FAQ block, or the Elementor, Bricks or Beaver module), and whether ThinkRank is publishing FAQPage schema for the post. Call this before update-faq: it reports which builder renders the post, and update-faq can only write posts built with the block editor. Read writable_reason before acting on a post that is not writable, and questions_readable before trusting the question count. Oxygen and Breakdance pages have no ThinkRank FAQ module, so their own accordions are read instead and reported with source oxygen or breakdance; those questions reach FAQPage schema only while the accordion setting in Schema Settings is on, which it is not by default. Note that Google shows FAQ rich results only for well-known, authoritative government and health websites, so for most sites the value of an FAQ is being quotable by answer engines, not a rich result.', 'thinkrank' );
48	}
49
50	/**
51	* {@inheritDoc}
52	*
53	* @return array<string, bool\|float\|string>
54	*/
55	public function get_annotations() {
56	return [
57	'readonly' => true,
58	'destructive' => false,
59	'idempotent' => true,
60	'priority' => 0.6,
61	'openWorldHint' => false,
62	];
63	}
64
65	/**
66	* {@inheritDoc}
67	*
68	* @return array<string, mixed>
69	*/
70	public function get_input_schema() {
71	return [
72	'type' => 'object',
73	'additionalProperties' => false,
74	'required' => [ 'post_id' ],
75	'properties' => [
76	'post_id' => [
77	'type' => 'integer',
78	'description' => __( 'Post ID from list-content-items.', 'thinkrank' ),
79	],
80	],
81	];
82	}
83
84	/**
85	* {@inheritDoc}
86	*
87	* @return array<string, mixed>
88	*/
89	public function get_output_schema() {
90	return [
91	'type' => 'object',
92	'properties' => [
93	'post_id' => [ 'type' => 'integer' ],
94	'post_title' => [ 'type' => 'string' ],
95	'post_type' => [ 'type' => 'string' ],
96	'permalink' => [ 'type' => 'string' ],
97	'edit_url' => [ 'type' => 'string' ],
98	'builder' => [
99	'type' => 'string',
100	'enum' => $this->builder_enum(),
101	'description' => __( 'Which page builder renders this post. Anything but "none" means update-faq will refuse it. "none" means the block editor, not "no builder was recognised".', 'thinkrank' ),
102	],
103	'writable' => [
104	'type' => 'boolean',
105	'description' => __( 'True when update-faq can write this post. False for builder-rendered posts, where a block would be stored but never shown.', 'thinkrank' ),
106	],
107	'writable_reason' => [
108	'type' => 'string',
109	'description' => __( 'Why update-faq will or will not write this post, in a sentence. Read this before deciding what to do with a post that is not writable: a builder ThinkRank has a FAQ module for is a different situation from one it only recognises.', 'thinkrank' ),
110	],
111	'questions_readable' => [
112	'type' => 'boolean',
113	'description' => __( 'Whether ThinkRank can read the questions this post stores. False for a builder with no ThinkRank FAQ module, where total and items describe only what is left in the post content and a count of zero does not mean the page has no FAQ.', 'thinkrank' ),
114	],
115	'faqpage_emitted' => [
116	'type' => 'boolean',
117	'description' => __( 'Whether ThinkRank currently publishes FAQPage schema for this post. False with questions present means the post is password protected, the content type has Schema off, a producer has its schema toggle off, or another plugin already publishes its own FAQPage here.', 'thinkrank' ),
118	],
119	'total' => [ 'type' => 'integer' ],
120	'items' => [
121	'type' => 'array',
122	'items' => [
123	'type' => 'object',
124	'properties' => $this->item_properties(),
125	],
126	],
127	],
128	];
129	}
130
131	/**
132	* Execute ability.
133	*
134	* @param array<string, mixed> $input Ability input payload.
135	* @return array<string, mixed>\|\WP_Error
136	*/
137	public function execute( $input ) {
138	$input = (array) $input;
139	$post = $this->resolve_post( (int) ( $input['post_id'] ?? 0 ) );
140
141	if ( $post instanceof \WP_Error ) {
142	return $post;
143	}
144
145	$items = FAQ_Content::items( $post );
146	$builder = FAQ_Content::builder( (int) $post->ID );
147
148	return [
149	'post_id' => (int) $post->ID,
150	'post_title' => (string) get_the_title( $post ),
151	'post_type' => (string) $post->post_type,
152	'permalink' => (string) get_permalink( $post ),
153	'edit_url' => (string) get_edit_post_link( $post->ID, 'raw' ),
154	'builder' => $this->builder_name( $builder ),
155	'writable' => '' === $builder,
156	'writable_reason' => $this->writable_reason( $builder ),
157	'questions_readable' => FAQ_Content::builder_is_readable( $builder ),
158	'faqpage_emitted' => Schema_Graph::will_emit_faqpage( $post ),
159	'total' => count( $items ),
160	'items' => $items,
161	];
162	}
163	}
164