$extra_data Additional non-sensitive data; cannot override the contract keys. * @return WP_Error */ public static function error( string $feature, string $required_plan, string $plan_message, string $code = 'premium_required', array $extra_data = array() ): WP_Error { $required_plan = self::normalizeRequiredPlan( $required_plan ); $reason = self::reason( $feature, $required_plan ); return new WP_Error( $code, self::message( $reason, $plan_message ), array( 'status' => 403, 'reason' => $reason, 'feature' => $feature, 'required_plan' => $required_plan, ) + $extra_data ); } /** * Build the 403 plan denial for a public (unauthenticated) route. * * Same envelope as error(), but always shaped as plan_required with the * caller's plan copy: anonymous visitors must never learn whether the * site's license could not be verified, needs attention or lacks the * premium code. It resolves no reason, so it never evaluates entitlement. * Admin-facing routes keep using error(). * * @param string $feature Feature key of the denied capability. * @param string $required_plan PLAN_PAID or PLAN_BUSINESS (anything else is treated as PLAN_BUSINESS). * @param string $plan_message The caller's translated plan copy. * @param string $code Error code. * @return WP_Error */ public static function publicError( string $feature, string $required_plan, string $plan_message, string $code = 'premium_required' ): WP_Error { return new WP_Error( $code, $plan_message, array( 'status' => 403, 'reason' => self::REASON_PLAN_REQUIRED, 'feature' => $feature, 'required_plan' => self::normalizeRequiredPlan( $required_plan ), ) ); } /** * Override premium-code detection for tests. * * @internal PHPUnit use only. A production no-op. * @param bool|null $loaded Forced state, or null to restore detection. * @return void */ public static function setPremiumCodeLoadedForTesting( ?bool $loaded ): void { if ( ! self::isTestEnvironment() ) { return; } self::$premium_code_loaded_override = $loaded; } /** * Whether the premium plugin code is loaded on this request. * * @return bool */ private static function isPremiumCodeLoaded(): bool { if ( null !== self::$premium_code_loaded_override ) { return self::$premium_code_loaded_override; } return class_exists( self::PREMIUM_MANAGER_CLASS, false ); } /** * Whether the Freemius SDK plan includes the required plan (message selection only). * * @param string $required_plan Normalized required plan. * @return bool */ private static function sdkPlanIncludes( string $required_plan ): bool { try { $fs_manager = FsManager::getInstance(); if ( ! $fs_manager->is_registered() ) { return false; } $plan = $fs_manager->getPlanType(); } catch ( \Throwable $e ) { return false; } if ( self::PLAN_BUSINESS === $required_plan ) { return 'business' === $plan; } return in_array( $plan, array( 'pro', 'business' ), true ); } /** * @param mixed $reason Candidate reason. * @return bool */ private static function isKnownReason( $reason ): bool { return in_array( $reason, array( self::REASON_PLAN_REQUIRED, self::REASON_PREMIUM_CODE_MISSING, self::REASON_LICENSE_UNVERIFIED, self::REASON_LICENSE_ATTENTION, ), true ); } /** * Unknown required plans resolve to the strictest plan so a Pro SDK plan is * never reported as including a feature it may not include. * * @param string $required_plan Raw required plan. * @return string */ private static function normalizeRequiredPlan( string $required_plan ): string { return self::PLAN_PAID === $required_plan ? self::PLAN_PAID : self::PLAN_BUSINESS; } /** * Whether we are running under the PHPUnit test harness (dev-only markers). * * @return bool */ private static function isTestEnvironment(): bool { return defined( 'PHPUNIT_COMPOSER_INSTALL' ) || defined( 'WP_TESTS_DOMAIN' ) || class_exists( '\\PHPUnit\\Framework\\TestCase', false ); } }