← All changes
|
includes/abilities/settings/class-settings-key-map.php
+196
-19
2.1.1
→
2.13.0
View file →
| @@ -74,9 +74,9 @@ | ||
| 74 | 74 | 'enabled' => self::boolean( __( 'Whether site identity management is active.', 'thinkrank' ) ), |
| 75 | 75 | 'site_name' => self::string( __( 'Official name of the site, used in titles and schema.', 'thinkrank' ) ), |
| 76 | 76 | 'site_description' => self::string( __( 'Short description of the site.', 'thinkrank' ) ), |
| 77 | 77 | 'tagline' => self::string( __( 'Site tagline.', 'thinkrank' ) ), |
| 78 | - 'alternate_name' => self::string( __( 'Alternate or former name of the site, published as schema alternateName.', 'thinkrank' ) ), | |
| 78 | + 'alternate_name' => self::alternate_name(), | |
| 79 | 79 | 'identity_type' => self::string( __( 'What the site is, e.g. "blog", "business", "portfolio".', 'thinkrank' ) ), |
| 80 | 80 | 'represents' => self::string( __( 'Whether the site represents a "person" or an "organization".', 'thinkrank' ) ), |
| 81 | 81 | 'default_meta_description' => self::string( __( 'Meta description used where no more specific one is set.', 'thinkrank' ) ), |
| 82 | 82 | 'default_social_image' => self::string( __( 'URL of the fallback social sharing image.', 'thinkrank' ) ), |
| @@ -90,8 +90,15 @@ | ||
| 90 | 90 | // without stripping their tokens. |
| 91 | 91 | 'title_template' => self::string( __( 'Named title layout, e.g. "default", "reverse", "category".', 'thinkrank' ) ), |
| 92 | 92 | 'title_separator' => self::string( __( 'Separator between title parts, e.g. "pipe", "dash".', 'thinkrank' ) ), |
| 93 | 93 | 'homepage_title' => self::template( __( 'the homepage', 'thinkrank' ), '' ), |
| 94 | + 'homepage_description' => self::string( | |
| 95 | + sprintf( | |
| 96 | + /* translators: %s: the list of available variable tags. */ | |
| 97 | + __( 'Meta description for the homepage when it lists the latest posts. Available tags: %s. A static front page uses its own page description instead.', 'thinkrank' ), | |
| 98 | + '%site_title%, %site_name%, %site_description%, %tagline%, %sep%' | |
| 99 | + ) | |
| 100 | + ), | |
| 94 | 101 | 'category_title' => self::template( __( 'category archives', 'thinkrank' ), '%category_title%, %category%' ), |
| 95 | 102 | 'tag_title' => self::template( __( 'tag archives', 'thinkrank' ), '%tag_title%' ), |
| 96 | 103 | 'author_title' => self::template( __( 'author archives', 'thinkrank' ), '%author_name%' ), |
| 97 | 104 | 'search_title' => self::template( __( 'search results pages', 'thinkrank' ), '%search_term%' ), |
| @@ -103,8 +110,9 @@ | ||
| 103 | 110 | 'breadcrumb_home_text' => self::string( __( 'Label for the home link in breadcrumbs.', 'thinkrank' ) ), |
| 104 | 111 | 'breadcrumb_separator' => self::string( __( 'Separator drawn between breadcrumb items.', 'thinkrank' ) ), |
| 105 | 112 | 'breadcrumb_prefix' => self::string( __( 'Text shown before the breadcrumb trail.', 'thinkrank' ) ), |
| 106 | 113 | 'show_current_page' => self::boolean( __( 'Whether the current page appears in its own breadcrumb trail.', 'thinkrank' ) ), |
| 114 | + 'breadcrumb_use_seo_title' => self::boolean( __( 'Whether breadcrumb labels use the SEO title of a post or term when one is set, instead of its raw title.', 'thinkrank' ) ), | |
| 107 | 115 | |
| 108 | 116 | // Brand imagery. |
| 109 | 117 | 'logo_url' => self::string( __( 'URL of the site logo.', 'thinkrank' ) ), |
| 110 | 118 | 'favicon_url' => self::string( __( 'URL of the site favicon.', 'thinkrank' ) ), |
| @@ -119,9 +127,22 @@ | ||
| 119 | 127 | |
| 120 | 128 | // Business / Local SEO. Feeds LocalBusiness schema. |
| 121 | 129 | 'local_seo_enabled' => self::boolean( __( 'Whether Local SEO output and LocalBusiness schema are enabled.', 'thinkrank' ) ), |
| 122 | 130 | 'business_name' => self::string( __( 'Registered business name.', 'thinkrank' ) ), |
| 123 | - 'business_type' => self::string( __( 'schema.org business type, e.g. "Restaurant", "Store".', 'thinkrank' ) ), | |
| 131 | + // Enumerated rather than free-form: the value goes straight into | |
| 132 | + // LocalBusiness schema, so an invented type is invalid structured | |
| 133 | + // data. ~150 schema.org subtypes are accepted (#623). | |
| 134 | + // | |
| 135 | + // '' is in the list because it is a real stored state ("not set"): | |
| 136 | + // the store holds it on every site that never opened Local SEO, and | |
| 137 | + // without it the READ ability failed its own output schema on those | |
| 138 | + // sites and there was no way to clear the value over MCP. It goes | |
| 139 | + // last so the root stays first, which read() falls back to. | |
| 140 | + 'business_type' => [ | |
| 141 | + 'type' => 'string', | |
| 142 | + 'enum' => array_merge( \ThinkRank\Config\Local_Business_Types_Config::get_types(), [ '' ] ), | |
| 143 | + 'description' => __( 'schema.org LocalBusiness type, e.g. "Restaurant", "HealthAndBeautyBusiness". "LocalBusiness" is the general-purpose default and is always valid. An empty string means not set, and is published as LocalBusiness.', 'thinkrank' ), | |
| 144 | + ], | |
| 124 | 145 | 'business_email' => self::string( __( 'Public contact email address.', 'thinkrank' ) ), |
| 125 | 146 | 'business_phone' => self::string( __( 'Public contact telephone number.', 'thinkrank' ) ), |
| 126 | 147 | 'business_address' => self::string( __( 'Street address.', 'thinkrank' ) ), |
| 127 | 148 | 'business_city' => self::string( __( 'City or locality.', 'thinkrank' ) ), |
| @@ -134,9 +155,21 @@ | ||
| 134 | 155 | 'business_hours' => self::business_hours(), |
| 135 | 156 | |
| 136 | 157 | // Indexing. |
| 137 | 158 | 'allow_search_engines' => self::boolean( __( 'Whether search engines are allowed to index the site.', 'thinkrank' ) ), |
| 159 | + 'query_protection' => self::boolean( __( 'Whether a URL whose content selector resolved to nothing (for example ?post_type=nosuchtype) answers 404 instead of serving the blog listing at 200.', 'thinkrank' ) ), | |
| 160 | + 'canonical_scheme' => [ | |
| 161 | + 'type' => 'string', | |
| 162 | + 'description' => __( 'Scheme for canonical URLs, og:url, schema @ids and sitemap entries. "automatic" follows WordPress; the other two override it, for a site behind a proxy that terminates TLS and leaves WordPress reporting the wrong scheme.', 'thinkrank' ), | |
| 163 | + 'enum' => \ThinkRank\SEO\Url_Scheme::MODES, | |
| 164 | + ], | |
| 138 | 165 | 'robots_txt_enabled' => self::boolean( __( 'Whether ThinkRank manages robots.txt. Its contents are set with thinkrank/update-robots-txt.', 'thinkrank' ) ), |
| 166 | + | |
| 167 | + // RSS feeds. | |
| 168 | + 'feed_excerpt_only' => self::boolean( __( 'Whether feed entries are shortened to an excerpt instead of carrying the full post.', 'thinkrank' ) ), | |
| 169 | + 'feed_source_link' => self::boolean( __( 'Whether each feed entry is signed with a link back to the original post and the site.', 'thinkrank' ) ), | |
| 170 | + 'feed_noindex' => self::boolean( __( 'Whether feeds are served with X-Robots-Tag: noindex. Leave off for a podcast feed, which needs to be indexable.', 'thinkrank' ) ), | |
| 171 | + 'ai_crawler_rules' => self::ai_crawler_rules(), | |
| 139 | 172 | ]; |
| 140 | 173 | } |
| 141 | 174 | |
| 142 | 175 | /** |
| @@ -146,8 +179,13 @@ | ||
| 146 | 179 | */ |
| 147 | 180 | public static function sitemap(): array { |
| 148 | 181 | return [ |
| 149 | 182 | 'enabled' => self::boolean( __( 'Whether XML sitemap generation is active.', 'thinkrank' ) ), |
| 183 | + 'delivery_mode' => [ | |
| 184 | + 'type' => 'string', | |
| 185 | + 'enum' => \ThinkRank\SEO\Sitemap_Generator::DELIVERY_MODES, | |
| 186 | + 'description' => __( 'How the sitemap reaches crawlers. "auto" writes files when the WordPress root is writable and serves the sitemap from WordPress when it is not. "static" always writes files, and fails where that is not possible. "dynamic" always serves from WordPress and writes nothing.', 'thinkrank' ), | |
| 187 | + ], | |
| 150 | 188 | 'auto_generate' => self::boolean( __( 'Whether the sitemap regenerates automatically when content changes.', 'thinkrank' ) ), |
| 151 | 189 | 'use_sitemap_index' => self::boolean( __( 'Whether to publish a sitemap index that links per-type sitemaps, rather than one flat file.', 'thinkrank' ) ), |
| 152 | 190 | 'links_per_sitemap' => [ |
| 153 | 191 | 'type' => 'integer', |
| @@ -158,8 +196,14 @@ | ||
| 158 | 196 | 'custom_url_pattern' => self::string( __( 'Filename pattern for generated sitemaps, e.g. "sitemap-{type}.xml".', 'thinkrank' ) ), |
| 159 | 197 | 'enable_styling' => self::boolean( __( 'Whether an XSL stylesheet is attached so the sitemap is readable in a browser.', 'thinkrank' ) ), |
| 160 | 198 | 'ping_search_engines' => self::boolean( __( 'Whether search engines are notified after the sitemap is regenerated.', 'thinkrank' ) ), |
| 161 | 199 | |
| 200 | + // How the styled sitemap looks. All four need enable_styling on. | |
| 201 | + 'styling_logo' => self::boolean( __( 'Whether a logo is shown above the sitemap heading. Requires enable_styling.', 'thinkrank' ) ), | |
| 202 | + 'styling_logo_url' => self::string( __( 'URL of the sitemap logo image. Empty falls back to the site icon.', 'thinkrank' ) ), | |
| 203 | + 'styling_color_main' => self::string( __( 'Hex colour ("#rrggbb") for the sitemap header, links and table head. Empty keeps the stock palette.', 'thinkrank' ) ), | |
| 204 | + 'styling_color_accent' => self::string( __( 'Hex colour ("#rrggbb") for the header gradient end and link hovers. Empty keeps the stock palette.', 'thinkrank' ) ), | |
| 205 | + | |
| 162 | 206 | // What goes in. |
| 163 | 207 | 'include_posts' => self::boolean( __( 'Whether posts are included.', 'thinkrank' ) ), |
| 164 | 208 | 'include_pages' => self::boolean( __( 'Whether pages are included.', 'thinkrank' ) ), |
| 165 | 209 | 'include_categories' => self::boolean( __( 'Whether category archives are included.', 'thinkrank' ) ), |
| @@ -180,8 +224,17 @@ | ||
| 180 | 224 | * |
| 181 | 225 | * The store keeps everything as strings ("1"/""), so each value is coerced |
| 182 | 226 | * back to the type the schema advertises before it reaches an agent. |
| 183 | 227 | * |
| 228 | + * The same properties are the read ability's OUTPUT schema, which the | |
| 229 | + * Abilities API validates, and one value that fails it fails the whole | |
| 230 | + * call. So what comes out has to fit the schema for any stored value, not | |
| 231 | + * only for what today's save path writes: a business type imported before | |
| 232 | + * the list was enumerated, or a crawler rule whose crawler a filter has | |
| 233 | + * since removed, used to turn every get-site-identity-settings call into | |
| 234 | + * ability_invalid_output. Hence the recursion into objects, and the enum | |
| 235 | + * fallback in read_value(). | |
| 236 | + * | |
| 184 | 237 | * @param array<string, array<string, mixed>> $properties Schema properties for the category. |
| 185 | 238 | * @param array<string, mixed> $stored Settings as the manager returns them. |
| 186 | 239 | * @return array<string, mixed> Exposed settings, one entry per declared key. |
| 187 | 240 | */ |
| @@ -188,27 +241,86 @@ | ||
| 188 | 241 | public static function read( array $properties, array $stored ): array { |
| 189 | 242 | $out = []; |
| 190 | 243 | |
| 191 | 244 | foreach ( $properties as $key => $property ) { |
| 192 | - $value = $stored[ $key ] ?? null; | |
| 245 | + $out[ $key ] = self::read_value( $property, $stored[ $key ] ?? null ); | |
| 246 | + } | |
| 193 | 247 | |
| 194 | - switch ( $property['type'] ) { | |
| 195 | - case 'boolean': | |
| 196 | - $out[ $key ] = (bool) $value; | |
| 197 | - break; | |
| 198 | - case 'integer': | |
| 199 | - $out[ $key ] = (int) $value; | |
| 200 | - break; | |
| 201 | - case 'array': | |
| 202 | - case 'object': | |
| 203 | - $out[ $key ] = is_array( $value ) ? $value : []; | |
| 204 | - break; | |
| 205 | - default: | |
| 206 | - $out[ $key ] = (string) ( $value ?? '' ); | |
| 207 | - } | |
| 248 | + return $out; | |
| 249 | + } | |
| 250 | + | |
| 251 | + /** | |
| 252 | + * Coerce one stored value to the shape its property declares. | |
| 253 | + * | |
| 254 | + * An enumerated string that holds something outside its enum reads as the | |
| 255 | + * enum's FIRST entry. Every enum in this map is ordered so that entry is | |
| 256 | + * the value its manager falls back to for anything unrecognised | |
| 257 | + * (`automatic`, `auto`, `allow`, `LocalBusiness`), so the agent is told | |
| 258 | + * what the site actually does rather than a value it would be refused if | |
| 259 | + * it wrote it back. | |
| 260 | + * | |
| 261 | + * @since 2.10.0 | |
| 262 | + * | |
| 263 | + * @param array<string, mixed> $property Schema property. | |
| 264 | + * @param mixed $value Stored value, or null when absent. | |
| 265 | + * @return mixed | |
| 266 | + */ | |
| 267 | + private static function read_value( array $property, $value ) { | |
| 268 | + $type = $property['type'] ?? 'string'; | |
| 269 | + | |
| 270 | + // A union type ('string' or a list of them) keeps whichever shape | |
| 271 | + // it arrived in: casting to string would flatten a list, and | |
| 272 | + // casting to array would replace a name with [] (#692). | |
| 273 | + if ( is_array( $type ) ) { | |
| 274 | + return is_array( $value ) | |
| 275 | + ? array_values( array_map( 'strval', array_filter( $value, 'is_scalar' ) ) ) | |
| 276 | + : ( is_scalar( $value ) ? (string) $value : '' ); | |
| 208 | 277 | } |
| 209 | 278 | |
| 210 | - return $out; | |
| 279 | + switch ( $type ) { | |
| 280 | + case 'boolean': | |
| 281 | + return (bool) $value; | |
| 282 | + case 'integer': | |
| 283 | + return (int) $value; | |
| 284 | + case 'array': | |
| 285 | + if ( ! is_array( $value ) ) { | |
| 286 | + return []; | |
| 287 | + } | |
| 288 | + if ( isset( $property['items'] ) && is_array( $property['items'] ) ) { | |
| 289 | + $items = $property['items']; | |
| 290 | + return array_values( array_map( static fn( $item ) => self::read_value( $items, $item ), $value ) ); | |
| 291 | + } | |
| 292 | + return $value; | |
| 293 | + case 'object': | |
| 294 | + if ( ! is_array( $value ) ) { | |
| 295 | + return []; | |
| 296 | + } | |
| 297 | + if ( empty( $property['properties'] ) || ! is_array( $property['properties'] ) ) { | |
| 298 | + return $value; | |
| 299 | + } | |
| 300 | + | |
| 301 | + $declared = $property['properties']; | |
| 302 | + $closed = isset( $property['additionalProperties'] ) && false === $property['additionalProperties']; | |
| 303 | + $object = []; | |
| 304 | + | |
| 305 | + foreach ( $value as $name => $item ) { | |
| 306 | + if ( isset( $declared[ $name ] ) ) { | |
| 307 | + $object[ $name ] = self::read_value( $declared[ $name ], $item ); | |
| 308 | + } elseif ( ! $closed ) { | |
| 309 | + $object[ $name ] = $item; | |
| 310 | + } | |
| 311 | + } | |
| 312 | + | |
| 313 | + return $object; | |
| 314 | + default: | |
| 315 | + $string = is_scalar( $value ) ? (string) $value : ''; | |
| 316 | + | |
| 317 | + if ( ! empty( $property['enum'] ) && ! in_array( $string, $property['enum'], true ) ) { | |
| 318 | + return (string) reset( $property['enum'] ); | |
| 319 | + } | |
| 320 | + | |
| 321 | + return $string; | |
| 322 | + } | |
| 211 | 323 | } |
| 212 | 324 | |
| 213 | 325 | /** |
| 214 | 326 | * Coerce an incoming patch to the declared types, dropping unknown keys. |
| @@ -231,9 +343,21 @@ | ||
| 231 | 343 | } |
| 232 | 344 | |
| 233 | 345 | $value = $incoming[ $key ]; |
| 234 | 346 | |
| 235 | - switch ( $property['type'] ) { | |
| 347 | + $type = $property['type'] ?? 'string'; | |
| 348 | + | |
| 349 | + // A union type ('string' or a list of them) keeps whichever shape | |
| 350 | + // it arrived in: casting to string would flatten a list, and | |
| 351 | + // casting to array would replace a name with [] (#692). | |
| 352 | + if ( is_array( $type ) ) { | |
| 353 | + $out[ $key ] = is_array( $value ) | |
| 354 | + ? array_values( array_map( 'strval', $value ) ) | |
| 355 | + : (string) ( $value ?? '' ); | |
| 356 | + continue; | |
| 357 | + } | |
| 358 | + | |
| 359 | + switch ( $type ) { | |
| 236 | 360 | case 'boolean': |
| 237 | 361 | $out[ $key ] = (bool) $value; |
| 238 | 362 | break; |
| 239 | 363 | case 'integer': |
| @@ -308,13 +432,66 @@ | ||
| 308 | 432 | ]; |
| 309 | 433 | } |
| 310 | 434 | |
| 311 | 435 | /** |
| 436 | + * The per-agent AI crawler allow/block map. | |
| 437 | + * | |
| 438 | + * Enumerating the known slugs rather than accepting a free-form object is | |
| 439 | + * what makes this usable by an agent: the alternative is a caller guessing | |
| 440 | + * `chatgpt` for a crawler registered as `chatgpt-user`, having the key | |
| 441 | + * dropped as unknown, and being told the save succeeded — because it did, | |
| 442 | + * with nothing in it. | |
| 443 | + * | |
| 444 | + * @return array<string, mixed> | |
| 445 | + */ | |
| 446 | + private static function ai_crawler_rules(): array { | |
| 447 | + $properties = []; | |
| 448 | + | |
| 449 | + foreach ( \ThinkRank\SEO\AI_Crawlers::for_display() as $agent ) { | |
| 450 | + $properties[ $agent['slug'] ] = [ | |
| 451 | + 'type' => 'string', | |
| 452 | + 'enum' => [ 'allow', 'block' ], | |
| 453 | + /* translators: 1: crawler user-agent token, e.g. GPTBot. 2: what that crawler is for. */ | |
| 454 | + 'description' => sprintf( __( '%1$s — %2$s', 'thinkrank' ), $agent['token'], $agent['purpose'] ), | |
| 455 | + ]; | |
| 456 | + } | |
| 457 | + | |
| 458 | + return [ | |
| 459 | + 'type' => 'object', | |
| 460 | + 'description' => __( 'Per-agent AI crawler rules. "block" writes a User-agent/Disallow pair for that crawler into robots.txt; "allow" (the default for any crawler not listed) writes nothing. Blocking Google-Extended does not affect normal Google Search indexing.', 'thinkrank' ), | |
| 461 | + 'additionalProperties' => false, | |
| 462 | + 'properties' => $properties, | |
| 463 | + ]; | |
| 464 | + } | |
| 465 | + | |
| 466 | + /** | |
| 312 | 467 | * A boolean property. |
| 313 | 468 | * |
| 314 | 469 | * @param string $description Translated text describing what the toggle does. |
| 315 | 470 | * @return array<string, mixed> |
| 316 | 471 | */ |
| 472 | + /** | |
| 473 | + * The site's alternate name, as one value or several. | |
| 474 | + * | |
| 475 | + * schema.org and Google both allow `alternateName` to carry a list, and the | |
| 476 | + * store already round-trips either shape, so the schema says so rather than | |
| 477 | + * forcing a caller to pick one name and drop the rest (#692). | |
| 478 | + * | |
| 479 | + * @since 2.7.0 | |
| 480 | + * @return array<string, mixed> | |
| 481 | + */ | |
| 482 | + private static function alternate_name(): array { | |
| 483 | + return [ | |
| 484 | + // A union rather than anyOf: read() and coerce() switch on `type`, | |
| 485 | + // and an entry without one is dropped as unrecognised. WordPress's | |
| 486 | + // schema validator accepts a type list, so this is both valid JSON | |
| 487 | + // Schema and legible to this file's own consumers. | |
| 488 | + 'type' => [ 'string', 'array' ], | |
| 489 | + 'items' => [ 'type' => 'string' ], | |
| 490 | + 'description' => __( 'Alternate or former name of the site, published as schema alternateName on the homepage WebSite node. Send a string for one name, or an array for several. Blank entries and duplicates are dropped, and a single surviving name is published as a string.', 'thinkrank' ), | |
| 491 | + ]; | |
| 492 | + } | |
| 493 | + | |
| 317 | 494 | private static function boolean( string $description ): array { |
| 318 | 495 | return [ |
| 319 | 496 | 'type' => 'boolean', |
| 320 | 497 | 'description' => $description, |