use_cases, compat -> compatibility, catIntro -> category_intro, * catGroups -> product_groups, catGuide -> buying_guide, * catClose -> category_closing; `shipping_returns` and `cta` added later, * description generator only), * plus the Title part-key and SEO token-key catalogs for the two non-section * generators that still need a fixed, labelled vocabulary. * * This class is otherwise pure and context-free: `get()`/`typesFor()`/ * `allowsMode()`/`allowsFormat()` do no database or WooCommerce access, which * keeps them cheap to call on every `GET /content-structure/catalog` request * and trivial to unit test. The one deliberate exception is `newSection()` * materializing a `warranty` section: its default `condition` is resolved * against the live, store-specific custom-field allowlist (via * `FieldCatalog`), since the catalog's own field vocabulary ('meta:_warranty') * is only a USABLE default when that key actually is allowlisted for this * store. Resolution: `meta:_warranty` allowlisted -> condition enabled, * pointed at it (matches the prototype's own warranty default, * `cond:{on:true, field:'_warranty', op:'not_empty'}`); otherwise -> a * disabled placeholder, pointed at a same-named attribute ref if one is * discoverable (`attr:warranty` / `attr:pa_warranty`) or '' otherwise. A * disabled condition's field is never evaluated and never validated * against the catalog (see `DefinitionNormalizer`), so the placeholder case * can never fail validation even when the guessed attribute ref does not * exist. "Warranty AI only when warranty data exists" is satisfied either * way: `missing.policy` defaults to `'skip'`, and the execution engine's * per-type required-data heuristic (warranty needs a * non-empty warranty value from its allowed sources) runs before any model * call regardless of whether the user-visible `condition` ended up enabled. * * @package AIPT\Core\ContentStructure\Domain * @since 2.8.0 */ namespace AIPT\Core\ContentStructure\Domain; defined( 'ABSPATH' ) || exit; /** * Static catalog of section types, title part keys and SEO token keys. */ final class SectionCatalog { /** * Section types belonging to the `description` generator's pool, in * library display order: each library group's types together, the * groups in {@see groupLabels()} order. */ private const DESCRIPTION_TYPES = array( 'opening', 'supporting', 'summary', 'cta', 'features', 'benefits', 'use_cases', 'specs', 'compatibility', 'care', 'warranty', 'shipping_returns', 'fixed', 'custom', 'customer_reviews', 'compare_similar', 'related_products', ); /** * Section types whose own AI call must never share a completion with any * other pending section (Business-only "sections from your store" * family; `customer_reviews` is the first member). Partitioned out of * the normal batch by {@see Generators\SectionGenerator::generate()}/ * {@see Generators\SectionGenerator::regenerateUnit()} via * {@see isIsolatedUnit()}, one extra `GenerationRoundRunner::run()` call * per distinct flagged type present, never per section instance. */ private const ISOLATED_UNIT_TYPES = array( 'customer_reviews', 'related_products' ); /** * Section types belonging to the `taxonomy` generator's pool, in library * display order: the 4 taxonomy-only types plus the shared `fixed` and * `custom` types. */ private const TAXONOMY_TYPES = array( 'category_intro', 'product_groups', 'buying_guide', 'category_closing', 'fixed', 'custom', ); /** * Base defaults shared by every section type before its own type-specific * overrides (below) are applied. Mirrors the prototype's shared `base` * shape in spirit; `condition.field` is '' rather than a guessed custom * field name (see class docblock). * * @var array */ private const BASE_DEFAULTS = array( 'enabled' => true, 'heading' => array( 'mode' => 'none', 'text' => '' ), 'focus' => '', 'detail' => 'balanced', 'length' => array( 'targetMin' => 60, 'targetMax' => 100, 'hardMax' => null ), 'items' => array( 'max' => 5 ), 'fixedText' => '', 'fields' => array( 'mode' => 'all', 'keys' => array() ), 'sources' => array( 'inherit' => true, 'refs' => array() ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), 'condition' => array( 'enabled' => false, 'field' => '', 'operator' => 'not_empty', 'value' => '' ), 'tone' => '', 'instruction' => '', ); /** * Per-type catalog entries. `description` is also the section's purpose * in the AI prompt (`PromptSpecBuilder`), so it is never shortened for * display; `hint` is the library's own one-line summary. `group` is the * library group (see {@see groupLabels()}). `modes` lists allowed modes * with the default first; `formats` maps each allowed mode to its * allowed formats, also default first; `defaults` holds only the keys * that differ from BASE_DEFAULTS, each a COMPLETE sub-object (never a * partial patch). * * @var array,factType:bool,defaults:array}> */ private static function definitions(): array { return array( 'opening' => array( 'label' => __( 'Opening paragraph', 'ai-product-tools' ), 'description' => __( 'The first paragraph a shopper reads; states the core value of the product.', 'ai-product-tools' ), 'hint' => __( 'The first thing shoppers read', 'ai-product-tools' ), 'group' => 'opening_closing', 'modes' => array( 'ai', 'fixed' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 80, 'targetMax' => 120, 'hardMax' => null ) ), ), 'supporting' => array( 'label' => __( 'Supporting paragraph', 'ai-product-tools' ), 'description' => __( 'A second paragraph that explains who the product is for or adds supporting detail.', 'ai-product-tools' ), 'hint' => __( 'Who it is for, or more detail', 'ai-product-tools' ), 'group' => 'opening_closing', 'modes' => array( 'ai', 'fixed' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 60, 'targetMax' => 100, 'hardMax' => null ) ), ), 'features' => array( 'label' => __( 'Features', 'ai-product-tools' ), 'description' => __( 'A short list of the product\'s standout features.', 'ai-product-tools' ), 'hint' => __( 'Standout features as a list', 'ai-product-tools' ), 'group' => 'selling_points', 'modes' => array( 'ai', 'data' ), 'formats' => array( 'ai' => array( 'bullets', 'numbered' ), 'data' => array( 'bullets', 'numbered' ) ), 'factType' => false, 'defaults' => array( 'items' => array( 'max' => 6 ), 'heading' => array( 'mode' => 'fixed', 'text' => __( 'Features', 'ai-product-tools' ) ), ), ), 'benefits' => array( 'label' => __( 'Benefits', 'ai-product-tools' ), 'description' => __( 'A short list of the practical benefits customers get from this product.', 'ai-product-tools' ), 'hint' => __( 'What the customer gains', 'ai-product-tools' ), 'group' => 'selling_points', 'modes' => array( 'ai' ), 'formats' => array( 'ai' => array( 'bullets', 'numbered' ) ), 'factType' => false, 'defaults' => array( 'items' => array( 'max' => 5 ), 'heading' => array( 'mode' => 'fixed', 'text' => __( 'Why it works', 'ai-product-tools' ) ), ), ), 'specs' => array( 'label' => __( 'Specifications', 'ai-product-tools' ), 'description' => __( 'Key specifications presented as direct product data.', 'ai-product-tools' ), 'hint' => __( 'Key specs from product data', 'ai-product-tools' ), 'group' => 'facts', 'modes' => array( 'data', 'ai' ), 'formats' => array( 'data' => array( 'table', 'bullets' ), 'ai' => array( 'table', 'bullets' ) ), 'factType' => true, 'defaults' => array( 'fields' => array( 'mode' => 'all', 'keys' => array() ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'warranty' => array( 'label' => __( 'Warranty', 'ai-product-tools' ), 'description' => __( 'Warranty information, shown only when warranty data is available.', 'ai-product-tools' ), 'hint' => __( 'Only when warranty data exists', 'ai-product-tools' ), 'group' => 'facts', 'modes' => array( 'ai', 'data' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'data' => array( 'paragraph' ) ), 'factType' => true, 'defaults' => array( 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), 'condition' => array( 'enabled' => false, 'field' => '', 'operator' => 'not_empty', 'value' => '' ), ), ), 'fixed' => array( 'label' => __( 'Fixed text', 'ai-product-tools' ), 'description' => __( 'A block of text you write once that is never rewritten by AI.', 'ai-product-tools' ), 'hint' => __( 'Your text, kept word for word', 'ai-product-tools' ), 'group' => 'own', 'modes' => array( 'fixed' ), 'formats' => array( 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'fixedText' => '' ), ), 'customer_reviews' => array( 'label' => __( 'What customers say', 'ai-product-tools' ), 'description' => __( 'A short, balanced AI summary of this product\'s own approved reviews. Skipped until it has enough of them.', 'ai-product-tools' ), 'hint' => __( 'AI summary of approved reviews', 'ai-product-tools' ), 'group' => 'store', 'modes' => array( 'ai' ), 'formats' => array( 'ai' => array( 'paragraph' ) ), 'factType' => true, 'defaults' => array( 'heading' => array( 'mode' => 'fixed', 'text' => __( 'What customers say', 'ai-product-tools' ) ), 'length' => array( 'targetMin' => 40, 'targetMax' => 80, 'hardMax' => null ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'compare_similar' => array( 'label' => __( 'Compare with similar products', 'ai-product-tools' ), 'description' => __( 'A table comparing this product with up to two similar products from your store. Skipped when none has details to compare.', 'ai-product-tools' ), 'hint' => __( 'A table with similar products', 'ai-product-tools' ), 'group' => 'store', 'modes' => array( 'data' ), 'formats' => array( 'data' => array( 'comparison' ) ), 'factType' => true, 'defaults' => array( 'heading' => array( 'mode' => 'fixed', 'text' => __( 'Compare with similar products', 'ai-product-tools' ) ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'related_products' => array( 'label' => __( 'Related products', 'ai-product-tools' ), 'description' => __( 'One or two sentences pointing shoppers to up to two related products and this product\'s category, each linked to its page. Skipped when there is nothing to link to.', 'ai-product-tools' ), 'hint' => __( 'Links to related products', 'ai-product-tools' ), 'group' => 'store', 'modes' => array( 'ai' ), 'formats' => array( 'ai' => array( 'paragraph' ) ), 'factType' => true, 'defaults' => array( 'heading' => array( 'mode' => 'fixed', 'text' => __( 'You may also like', 'ai-product-tools' ) ), 'length' => array( 'targetMin' => 15, 'targetMax' => 45, 'hardMax' => null ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'use_cases' => array( 'label' => __( 'Use cases', 'ai-product-tools' ), 'description' => __( 'Typical situations or ways customers use this product.', 'ai-product-tools' ), 'hint' => __( 'Ways customers use it', 'ai-product-tools' ), 'group' => 'selling_points', 'modes' => array( 'ai' ), 'formats' => array( 'ai' => array( 'bullets', 'numbered' ) ), 'factType' => false, 'defaults' => array( 'items' => array( 'max' => 4 ) ), ), 'care' => array( 'label' => __( 'Use & care', 'ai-product-tools' ), 'description' => __( 'Guidance on using and caring for the product.', 'ai-product-tools' ), 'hint' => __( 'How to use and look after it', 'ai-product-tools' ), 'group' => 'facts', 'modes' => array( 'ai', 'data' ), 'formats' => array( 'ai' => array( 'numbered', 'bullets' ), 'data' => array( 'numbered', 'bullets' ) ), 'factType' => true, 'defaults' => array( 'items' => array( 'max' => 5 ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'compatibility' => array( 'label' => __( 'Compatibility', 'ai-product-tools' ), 'description' => __( 'What this product is compatible with.', 'ai-product-tools' ), 'hint' => __( 'What it works with', 'ai-product-tools' ), 'group' => 'facts', 'modes' => array( 'data', 'ai' ), 'formats' => array( 'data' => array( 'bullets', 'table' ), 'ai' => array( 'bullets', 'table' ) ), 'factType' => true, 'defaults' => array( 'fields' => array( 'mode' => 'all', 'keys' => array() ), 'missing' => array( 'policy' => 'skip', 'fallbackText' => '' ), ), ), 'summary' => array( 'label' => __( 'Summary', 'ai-product-tools' ), 'description' => __( 'A short closing summary.', 'ai-product-tools' ), 'hint' => __( 'A short closing recap', 'ai-product-tools' ), 'group' => 'opening_closing', 'modes' => array( 'ai', 'fixed' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 12, 'targetMax' => 40, 'hardMax' => null ) ), ), 'custom' => array( 'label' => __( 'Custom section', 'ai-product-tools' ), 'description' => __( 'A section you define yourself, with your own focus.', 'ai-product-tools' ), 'hint' => __( 'Your own focus and format', 'ai-product-tools' ), 'group' => 'own', 'modes' => array( 'ai', 'fixed', 'data' ), 'formats' => array( 'ai' => array( 'paragraph', 'bullets', 'numbered', 'table' ), 'fixed' => array( 'paragraph' ), 'data' => array( 'paragraph', 'bullets', 'numbered', 'table' ), ), 'factType' => false, 'defaults' => array(), ), 'shipping_returns' => array( 'label' => __( 'Shipping & returns', 'ai-product-tools' ), 'description' => __( 'Delivery time, shipping cost and how to return this product.', 'ai-product-tools' ), 'hint' => __( 'Delivery, costs and returns', 'ai-product-tools' ), 'group' => 'facts', 'modes' => array( 'fixed', 'ai' ), 'formats' => array( 'fixed' => array( 'paragraph' ), 'ai' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'fixedText' => '' ), ), 'cta' => array( 'label' => __( 'Call to action', 'ai-product-tools' ), 'description' => __( 'A short closing line that encourages the shopper to buy.', 'ai-product-tools' ), 'hint' => __( 'Invites the shopper to buy', 'ai-product-tools' ), 'group' => 'opening_closing', 'modes' => array( 'ai', 'fixed' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 10, 'targetMax' => 30, 'hardMax' => null ) ), ), 'category_intro' => array( 'label' => __( 'Category introduction', 'ai-product-tools' ), 'description' => __( 'An introduction to this category for shoppers.', 'ai-product-tools' ), 'hint' => __( 'Introduces the category', 'ai-product-tools' ), 'group' => 'category', 'modes' => array( 'ai', 'fixed' ), 'formats' => array( 'ai' => array( 'paragraph' ), 'fixed' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 50, 'targetMax' => 80, 'hardMax' => null ) ), ), 'product_groups' => array( 'label' => __( 'Product groups', 'ai-product-tools' ), 'description' => __( 'The main ways products in this category are grouped.', 'ai-product-tools' ), 'hint' => __( 'How products here are grouped', 'ai-product-tools' ), 'group' => 'category', 'modes' => array( 'ai', 'data' ), 'formats' => array( 'ai' => array( 'bullets' ), 'data' => array( 'bullets' ) ), 'factType' => false, 'defaults' => array( 'items' => array( 'max' => 5 ), 'heading' => array( 'mode' => 'fixed', 'text' => __( 'Browse by type', 'ai-product-tools' ) ), ), ), 'buying_guide' => array( 'label' => __( 'Buying guide', 'ai-product-tools' ), 'description' => __( 'Guidance on how to choose within this category.', 'ai-product-tools' ), 'hint' => __( 'How to choose the right one', 'ai-product-tools' ), 'group' => 'category', 'modes' => array( 'ai' ), 'formats' => array( 'ai' => array( 'paragraph', 'bullets' ) ), 'factType' => false, 'defaults' => array( 'length' => array( 'targetMin' => 60, 'targetMax' => 110, 'hardMax' => null ), 'heading' => array( 'mode' => 'fixed', 'text' => __( 'How to choose', 'ai-product-tools' ) ), ), ), 'category_closing' => array( 'label' => __( 'Closing', 'ai-product-tools' ), 'description' => __( 'A closing note for the category page.', 'ai-product-tools' ), 'hint' => __( 'A closing note for the page', 'ai-product-tools' ), 'group' => 'category', 'modes' => array( 'fixed', 'ai' ), 'formats' => array( 'fixed' => array( 'paragraph' ), 'ai' => array( 'paragraph' ) ), 'factType' => false, 'defaults' => array( 'fixedText' => '' ), ), ); } /** * Title part-key catalog: label, allowed modes (default first) and a * suggested default FieldRef. `defaultField` is an editor pre-fill * suggestion only; DefinitionNormalizer validates whatever field the * saved part actually carries against the live FieldCatalog regardless. * * @return array */ public static function titlePartKeys(): array { return array( 'brand' => array( 'label' => __( 'Brand', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => '' ), 'product_name' => array( 'label' => __( 'Product name', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => 'core:name' ), 'product_type' => array( 'label' => __( 'Product type', 'ai-product-tools' ), 'modes' => array( 'data', 'ai', 'fixed' ), 'defaultField' => 'core:categories' ), 'key_feature' => array( 'label' => __( 'Key feature', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), 'model' => array( 'label' => __( 'Model', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => '' ), 'color' => array( 'label' => __( 'Color', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => 'attr:pa_color' ), 'material' => array( 'label' => __( 'Material', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => 'attr:pa_material' ), 'size' => array( 'label' => __( 'Size', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => 'attr:pa_size' ), 'pack' => array( 'label' => __( 'Pack', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => '' ), 'custom' => array( 'label' => __( 'Custom', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), ); } /** * SEO token-key catalog. `store_name` and `keyword` resolve specially at * generation time (site name / the blueprint's resolved focus keyword) * rather than through a product FieldRef, so their `defaultField` is ''. * * @return array */ public static function seoTokenKeys(): array { return array( 'product_name' => array( 'label' => __( 'Product name', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => 'core:name' ), 'key_feature' => array( 'label' => __( 'Key feature', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), 'store_name' => array( 'label' => __( 'Store name', 'ai-product-tools' ), 'modes' => array( 'data', 'fixed' ), 'defaultField' => '' ), 'benefit' => array( 'label' => __( 'Benefit', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), 'key_spec' => array( 'label' => __( 'Key spec', 'ai-product-tools' ), 'modes' => array( 'data', 'ai', 'fixed' ), 'defaultField' => '' ), 'cta' => array( 'label' => __( 'Call to action', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), 'keyword' => array( 'label' => __( 'Focus keyword', 'ai-product-tools' ), 'modes' => array( 'data' ), 'defaultField' => '' ), 'custom' => array( 'label' => __( 'Custom', 'ai-product-tools' ), 'modes' => array( 'ai', 'fixed' ), 'defaultField' => '' ), ); } /** * Ordered section types for one generator's library. * * Only `description` and `taxonomy` use section types; every other * generator returns an empty array. * * @param string $generator Generator key. * @return array Ordered map of type => catalog entry. */ public static function typesFor( string $generator ): array { if ( Generators::DESCRIPTION === $generator ) { $types = self::DESCRIPTION_TYPES; } elseif ( Generators::TAXONOMY === $generator ) { $types = self::TAXONOMY_TYPES; } else { return array(); } $result = array(); foreach ( $types as $type ) { $entry = self::get( $type ); if ( null !== $entry ) { $result[ $type ] = $entry; } } return $result; } /** * The section library's group headings, in display order. Every section * type belongs to exactly one group; the shared `fixed` and `custom` * types sit in `own` in both pools. * * @return array Group key => heading. */ public static function groupLabels(): array { return array( 'opening_closing' => __( 'Opening and closing', 'ai-product-tools' ), 'selling_points' => __( 'Selling points', 'ai-product-tools' ), 'facts' => __( 'Facts and policies', 'ai-product-tools' ), 'category' => __( 'Category page', 'ai-product-tools' ), 'own' => __( 'Your own sections', 'ai-product-tools' ), 'store' => __( 'From your store', 'ai-product-tools' ), ); } /** * One section type's full catalog entry. `isolated` tells the editor that * the type writes only from its own store data in its own call, so the * structure's sources never reach it. `groupLabel` is the heading of the * library group the type is listed under. * * @param string $type Section type key. * @return array{type:string,isolated:bool,groupLabel:string,label:string,description:string,hint:string,group:string,modes:string[],formats:array,factType:bool,defaults:array}|null */ public static function get( string $type ): ?array { $definitions = self::definitions(); if ( ! isset( $definitions[ $type ] ) ) { return null; } return array( 'type' => $type, 'isolated' => self::isIsolatedUnit( $type ), 'groupLabel' => self::groupLabels()[ $definitions[ $type ]['group'] ], ) + $definitions[ $type ]; } /** * Whether $type allows $mode. * * @param string $type Section type key. * @param string $mode Candidate mode. * @return bool */ public static function allowsMode( string $type, string $mode ): bool { $entry = self::get( $type ); return null !== $entry && in_array( $mode, $entry['modes'], true ); } /** * Whether $type's own AI call must run in isolation: never sharing a * single completion with any other pending section, picker, condition * or source. See {@see ISOLATED_UNIT_TYPES}. * * @param string $type Section type key. * @return bool */ public static function isIsolatedUnit( string $type ): bool { return in_array( $type, self::ISOLATED_UNIT_TYPES, true ); } /** * Whether $type allows $format while in $mode. * * @param string $type Section type key. * @param string $mode Mode (must itself be allowed for $type). * @param string $format Candidate format. * @return bool */ public static function allowsFormat( string $type, string $mode, string $format ): bool { $entry = self::get( $type ); return null !== $entry && isset( $entry['formats'][ $mode ] ) && in_array( $format, $entry['formats'][ $mode ], true ); } /** * Build a new, fully-defaulted section instance of $type. * * $overrides replaces whole top-level BlueprintSection keys; to override * a nested field (e.g. `length.targetMax`) pass the complete `length` * sub-object, not a partial patch. * * @param string $type Section type key. * @param array $overrides Caller overrides, applied last. * @return array A BlueprintSection-shaped array. */ public static function newSection( string $type, array $overrides = array() ): array { $entry = self::get( $type ); $section = self::BASE_DEFAULTS; if ( null !== $entry ) { $section = array_replace( $section, $entry['defaults'] ); } if ( 'warranty' === $type ) { $section['condition'] = self::warrantyCondition(); } $modes = null !== $entry ? $entry['modes'] : array( 'ai' ); $mode = $modes[0] ?? 'ai'; $format = null !== $entry && isset( $entry['formats'][ $mode ][0] ) ? $entry['formats'][ $mode ][0] : 'paragraph'; $section['mode'] = $mode; $section['format'] = $format; $section['type'] = $type; $section['name'] = null !== $entry ? $entry['label'] : $type; $section = array_replace( $section, $overrides ); $section['type'] = $type; $section['id'] = ( isset( $overrides['id'] ) && is_string( $overrides['id'] ) && '' !== $overrides['id'] ) ? $overrides['id'] : self::generateId(); return $section; } /** * Live-resolved default `condition` for "this subject has warranty * data": used both for a fresh `warranty` section (newSection()) and by * `Templates\TemplateCatalog` for the `use_care_compat` FAQ template's * Warranty group, so the two built-ins agree on how warranty data is * detected. See the class docblock for the resolution rule. * * @return array{enabled:bool,field:string,operator:string,value:string} */ public static function warrantyCondition(): array { $fields = new FieldCatalog(); if ( $fields->isValidRef( 'meta:_warranty', 'product' ) ) { return array( 'enabled' => true, 'field' => 'meta:_warranty', 'operator' => 'not_empty', 'value' => '' ); } foreach ( array( 'attr:warranty', 'attr:pa_warranty' ) as $guess ) { if ( $fields->isValidRef( $guess, 'product' ) ) { return array( 'enabled' => false, 'field' => $guess, 'operator' => 'not_empty', 'value' => '' ); } } return array( 'enabled' => false, 'field' => '', 'operator' => 'not_empty', 'value' => '' ); } /** * A stable, unique-enough section/part/token/group id. * * @param string $prefix Id prefix (letters/digits only; default 'sec'). * @return string "_" followed by 8 lowercase [a-z0-9] characters. */ public static function generateId( string $prefix = 'sec' ): string { return $prefix . '_' . substr( bin2hex( random_bytes( 4 ) ), 0, 8 ); } }