'product_attributes', 'term:product_descriptions' => 'product_descriptions', ); /** * @var FieldCatalog */ private $fields; /** * @var EntitlementPolicy */ private $policy; /** * @param FieldCatalog|null $fields Field catalog; a default instance is * constructed when omitted. * @param EntitlementPolicy|null $policy Entitlement policy; a default instance is * constructed when omitted. */ public function __construct( ?FieldCatalog $fields = null, ?EntitlementPolicy $policy = null ) { $this->fields = $fields ?? new FieldCatalog(); $this->policy = $policy ?? new EntitlementPolicy(); } /** * Historical sample count, used when a caller omits the new * `$sample_products` parameter (e.g. a definition saved before the * per-blueprint "Sample products per category" setting existed). */ private const DEFAULT_SAMPLE_PRODUCTS = 10; /** * Build the allowed term context. * * @param WP_Term $term Term. * @param string[] $allowed_refs FieldRefs to resolve (unordered); pass * every `term:*` ref the catalog exposes * when the caller has no narrower policy. * The paid-source refs are withheld, * and sampled-fact refs are capped, per * this site's taxonomy entitlements * regardless of what the caller passed. * @param int $sample_products The Blueprint's own "Sample products * per category" setting * (`structure.sampleProducts`, schema-bounded * 5..20), already clamped to this site's * entitlement by `EntitlementPolicy::apply()` * before the definition ever reaches here; * this site's `taxonomyMaxSamples()` ceiling * is re-applied below regardless, so a value * that somehow arrives unclamped (an older * stored definition, a direct engine call) * can never exceed it either. * @return array{text:string,facts:array,numericTokens:string[],fieldValues:array} */ public function build( WP_Term $term, array $allowed_refs, int $sample_products = self::DEFAULT_SAMPLE_PRODUCTS ): array { $ordered_refs = $this->orderedRefs( $allowed_refs ); return $this->composeFieldContext( $ordered_refs, function ( string $ref ) use ( $term, $sample_products ) { return $this->resolveField( $term, $ref, $sample_products ); }, function ( string $ref ) { return $this->fields->label( $ref ); } ); } /** * Resolve a single FieldRef, entitlement-gated (planner * condition/data-field use — see class docblock for why this is the * one path every caller, including {@see build()}, goes through). * * @param WP_Term $term Term. * @param string $ref FieldRef. * @param int $sample_products See {@see build()}. * @return array{type:string,value:mixed,empty:bool} */ public function resolveField( WP_Term $term, string $ref, int $sample_products = self::DEFAULT_SAMPLE_PRODUCTS ): array { if ( isset( self::PAID_SOURCE_BY_REF[ $ref ] ) && ! in_array( self::PAID_SOURCE_BY_REF[ $ref ], $this->policy->taxonomyAllowedSources(), true ) ) { return array( 'type' => 'pairs', 'value' => array(), 'empty' => true ); } return $this->capSamples( $ref, $this->fields->termValue( $term, $ref ), $sample_products ); } /** * Cap a sample-derived field's resolved list/pairs to the smaller of the * Blueprint's own requested sample count and this site's * `EntitlementPolicy::taxonomyMaxSamples()` ceiling. Deterministic (keeps * the first N, the FieldCatalog's own sample order) and a no-op for any * other ref. * * @param string $ref FieldRef just resolved. * @param array $resolved FieldCatalog's `{type,value,empty}`. * @param int $sample_products See {@see build()}. * @return array{type:string,value:mixed,empty:bool} */ private function capSamples( string $ref, array $resolved, int $sample_products ): array { if ( ! in_array( $ref, self::SAMPLE_CAPPED_REFS, true ) || ! is_array( $resolved['value'] ?? null ) ) { return $resolved; } $max = min( max( 1, $sample_products ), $this->policy->taxonomyMaxSamples() ); if ( count( $resolved['value'] ) <= $max ) { return $resolved; } $resolved['value'] = array_slice( $resolved['value'], 0, $max ); return $resolved; } /** * Label for a FieldRef (delegates to FieldCatalog). * * @param string $ref FieldRef. * @return string */ public function label( string $ref ): string { return $this->fields->label( $ref ); } /** * @param string[] $allowed_refs Allowed FieldRefs. * @return string[] */ private function orderedRefs( array $allowed_refs ): array { $allowed = array_fill_keys( $allowed_refs, true ); $ordered = array(); foreach ( $this->fields->forScope( 'term' ) as $entry ) { if ( isset( $allowed[ $entry['ref'] ] ) ) { $ordered[] = $entry['ref']; } } return $ordered; } }