= targetMax >= targetMin` intact after `hardMax` moves. * * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ public function clamp( array &$definition, array &$applied ): void { $title_hard = isset( $definition['structure']['title']['hardMax'] ) ? (int) $definition['structure']['title']['hardMax'] : self::FREE_SEO_TITLE_MAX; $desc_hard = isset( $definition['structure']['description']['hardMax'] ) ? (int) $definition['structure']['description']['hardMax'] : self::FREE_SEO_DESC_MAX; $keyword_source = (string) ( $definition['structure']['keyword']['source'] ?? 'focus_keyword' ); $controlled = $this->seoMetaControlledOptions( array( 'titleMaxLength' => $title_hard, 'descMaxLength' => $desc_hard, 'generateFocusKeyword' => ( 'generate' === $keyword_source ), ) ); $lengths_clamped = false; $allowed_title = isset( $controlled['titleMaxLength'] ) && is_numeric( $controlled['titleMaxLength'] ) ? (int) $controlled['titleMaxLength'] : self::FREE_SEO_TITLE_MAX; if ( $title_hard > $allowed_title ) { $this->clampSeoLengthField( $definition, 'title', $allowed_title ); $lengths_clamped = true; } $allowed_desc = isset( $controlled['descMaxLength'] ) && is_numeric( $controlled['descMaxLength'] ) ? (int) $controlled['descMaxLength'] : self::FREE_SEO_DESC_MAX; if ( $desc_hard > $allowed_desc ) { $this->clampSeoLengthField( $definition, 'description', $allowed_desc ); $lengths_clamped = true; } if ( $lengths_clamped ) { $applied[] = $this->freeDefault( 'seoMeta:length', 'seoMetaPremiumOptions', __( 'This template asked for a longer SEO title or description, so the standard lengths (60 and 160 characters) were used instead.', 'ai-product-tools' ), __( 'longer SEO titles and descriptions', 'ai-product-tools' ) ); } if ( 'generate' === $keyword_source && empty( $controlled['generateFocusKeyword'] ) ) { $definition['structure']['keyword']['source'] = 'focus_keyword'; $applied[] = $this->freeDefault( 'seoMeta:keyword', 'seoMetaPremiumOptions', __( 'This template asked for an AI-generated focus keyword, so only a focus keyword already saved on the product was used.', 'ai-product-tools' ), __( 'AI-generated focus keywords', 'ai-product-tools' ) ); } } /** * Replay `aipt_seo_meta_validate_options` over $requested with the free * defaults applied first, the request shape * `SeoMetaGeneratorController::apply_premium_controls()` builds. * * @param array{titleMaxLength:int,descMaxLength:int,generateFocusKeyword:bool} $requested Requested options. * @return array Controlled options. */ private function seoMetaControlledOptions( array $requested ): array { $free_defaults = array( 'titleMaxLength' => self::FREE_SEO_TITLE_MAX, 'descMaxLength' => self::FREE_SEO_DESC_MAX, 'generateFocusKeyword' => false, ); $controlled = apply_filters( 'aipt_seo_meta_validate_options', array_merge( $requested, $free_defaults ), $requested ); return is_array( $controlled ) ? $controlled : $free_defaults; } /** * The longest SEO meta title and description `hardMax` this site may * use: the Free ceilings, or the schema's own limits when entitled. * Public so the Blueprint editor stops its length inputs where * {@see clamp()} would. * * @return array{title:int,description:int} */ public function seoMetaLengthCeilings(): array { $controlled = $this->seoMetaControlledOptions( array( 'titleMaxLength' => DefinitionPrimitives::SEO_TITLE_CHARS_MAX, 'descMaxLength' => DefinitionPrimitives::SEO_DESC_CHARS_MAX, 'generateFocusKeyword' => false, ) ); return array( 'title' => min( DefinitionPrimitives::SEO_TITLE_CHARS_MAX, max( self::FREE_SEO_TITLE_MAX, (int) ( $controlled['titleMaxLength'] ?? 0 ) ) ), 'description' => min( DefinitionPrimitives::SEO_DESC_CHARS_MAX, max( self::FREE_SEO_DESC_MAX, (int) ( $controlled['descMaxLength'] ?? 0 ) ) ), ); } /** * Whether this site may ask the AI to write the focus keyword * (`keyword.source === 'generate'`). Public for the Blueprint editor, * the same decision {@see clamp()} makes. * * @return bool */ public function seoMetaKeywordAiAllowed(): bool { $controlled = $this->seoMetaControlledOptions( array( 'titleMaxLength' => self::FREE_SEO_TITLE_MAX, 'descMaxLength' => self::FREE_SEO_DESC_MAX, 'generateFocusKeyword' => true, ) ); return ! empty( $controlled['generateFocusKeyword'] ); } /** * @param array &$definition Clamped definition (mutated in place). * @param string $field 'title' | 'description'. * @param int $hard_max New hardMax ceiling. * @return void */ private function clampSeoLengthField( array &$definition, string $field, int $hard_max ): void { $definition['structure'][ $field ]['hardMax'] = $hard_max; if ( isset( $definition['structure'][ $field ]['targetMax'] ) && (int) $definition['structure'][ $field ]['targetMax'] > $hard_max ) { $definition['structure'][ $field ]['targetMax'] = $hard_max; } if ( isset( $definition['structure'][ $field ]['targetMin'], $definition['structure'][ $field ]['targetMax'] ) && (int) $definition['structure'][ $field ]['targetMin'] > (int) $definition['structure'][ $field ]['targetMax'] ) { $definition['structure'][ $field ]['targetMin'] = $definition['structure'][ $field ]['targetMax']; } } /** * Most SEO meta alternatives (`runOptions.variants`) this site may ask * for in one Blueprint-origin call. Reads the exact filter * `SeoMetaGeneratorService::bulk_generate_variants()` already applies * (`aipt_seo_meta_max_variants`, registered by * `Premium\BulkGenerator\SeoMeta\PremiumSeoMetaFeatures::getMaxVariants()`), * so a Blueprint-origin run (bulk, automation, editor, metabox, ability, * Test and preview) is capped the same way the legacy controller's own * variants path already is. * * Public: `runOptions.variants` is a run option, not a definition field, * and {@see EntitlementPolicy::apply()} only ever receives the resolved definition - the * same reason {@see TaxonomyPolicy::taxonomyMaxSamples()} and * {@see ImageAltPolicy::imageAltGalleryAllowed()} are public methods `ExecutionService` * calls directly where it reads `$run_options`, rather than a value * returned from `apply()`. Title stays unclamped - its alternative count * has never had an entitlement gate anywhere in the codebase, and this * method is never consulted for it. * * @return int */ public function seoMetaMaxVariants(): int { $max = apply_filters( 'aipt_seo_meta_max_variants', self::FREE_SEO_MAX_VARIANTS ); return ( is_int( $max ) && $max >= 1 ) ? $max : self::FREE_SEO_MAX_VARIANTS; } /** * The `appliedFreeDefaults` entry for a Blueprint-origin SEO meta run's * requested `runOptions.variants` being capped down to * {@see seoMetaMaxVariants()}. Reuses the `seoMetaPremiumOptions` feature * key {@see clamp()} already uses: the legacy * `aipt_seo_meta_max_variants` filter and `aipt_seo_meta_validate_options` * are gated by the exact same premium check * (`PremiumSeoMetaFeatures::canUsePremiumFeatures()`), so this is the * same entitlement, never a second gate with its own message variant. * * Added to the result only by a caller that already knows the REQUESTED * count actually exceeded the cap - * {@see \AIPT\Api\ContentStructure\Engine\ExecutionService} is where that * comparison is made (never this class, which has no run option to * compare against — {@see seoMetaMaxVariants()} is read directly by * `ExecutionService`, the same reason {@see ImageAltPolicy::imageAltGalleryFreeDefault()} * is only ever added by a caller that already knows a gallery image was * actually dropped for this run). * * @return array{key:string,reason:string} */ public function seoMetaVariantsFreeDefault(): array { return $this->freeDefault( 'seoMeta:variants', 'seoMetaPremiumOptions', __( 'This template asked for more SEO meta alternatives, so the standard number was written instead.', 'ai-product-tools' ), __( 'more alternatives', 'ai-product-tools' ) ); } }