sanitizer = new Settings_Sanitizer(); add_action( 'add_option_' . self::OPTION, array( $this, 'clear_cache' ) ); add_action( 'update_option_' . self::OPTION, array( $this, 'clear_cache' ) ); add_action( 'delete_option_' . self::OPTION, array( $this, 'clear_cache' ) ); add_action( 'switch_blog', array( $this, 'clear_cache' ) ); } /** * Return the centralized settings capability. * * @return string Required capability, shared by all future handlers. */ public static function capability() { return self::CAPABILITY; } /** * Build the canonical uncustomized settings tree. * * @return array Complete inherited defaults. */ public function defaults() { return Settings_Schema::defaults(); } /** Register WordPress's save flow, not a custom request handler. */ public function register() { if ( $this->registered ) { return; } if ( current_user_can( self::capability() ) ) { $this->initialize(); } register_setting( self::GROUP, self::OPTION, array( 'type' => 'array', 'default' => $this->defaults(), 'show_in_rest' => false, 'sanitize_callback' => array( $this, 'sanitize' ), ) ); add_filter( 'option_page_capability_' . self::GROUP, array( __CLASS__, 'capability' ) ); $this->registered = true; } /** * Return only validated values; missing storage is resolved without writes. * * @return array */ public function all() { if ( null === $this->cache ) { $this->stored = get_option( self::OPTION, null ); $migrated = $this->migrate( $this->stored ); $result = $this->sanitizer->validate( is_wp_error( $migrated ) ? array() : $migrated ); $this->cache = $result['settings']; } return $this->cache; } /** * Retrieve a normalized group without exposing raw option storage. * * @param string $group Group key. * @return array Unknown groups return an empty array. */ public function group( $group ) { $all = $this->all(); return is_string( $group ) && isset( $all[ $group ] ) && is_array( $all[ $group ] ) ? $all[ $group ] : array(); } /** * Retrieve a safe settings group or field. * * @param string $group Group key. * @param string $key Field key. * @param mixed $fallback Value for unknown fields only. * @return mixed */ public function get( $group, $key, $fallback = null ) { $values = $this->group( $group ); return is_string( $key ) && array_key_exists( $key, $values ) ? $values[ $key ] : $fallback; } /** * Distinguish an absent field from a stored explicit override, including zero. * * @param string $group Group key. * @param string $key Field key. * @return bool */ public function has_saved( $group, $key ) { $this->all(); $schema = Settings_Schema::fields(); return is_string( $group ) && is_string( $key ) && isset( $schema[ $group ][ $key ] ) && is_array( $this->stored ) && isset( $this->stored[ $group ] ) && is_array( $this->stored[ $group ] ) && array_key_exists( $key, $this->stored[ $group ] ); } /** * Validate a candidate without saving it or checking a browser nonce. * * @param mixed $input Unslashed settings. * @return array */ public function validate( $input ) { return $this->sanitizer->validate( $input ); } /** * Settings API callback: atomic rejection and sparse, idempotent output. * WordPress options.php checks the nonce and unslashes before this callback. * * @param mixed $input Candidate settings. * @return mixed Safe storage, or unchanged previous storage on rejection. */ public function sanitize( $input ) { $previous = get_option( self::OPTION, null ); if ( ! current_user_can( self::capability() ) ) { return $previous; } // Inspect the form envelope on every pass, including WordPress's second sanitization. if ( isset( $_POST['option_page'] ) && self::GROUP === $_POST['option_page'] ) { // phpcs:ignore WordPress.Security.NonceVerification.Missing -- options.php verifies the Settings API nonce. $submitted = isset( $_POST[ self::OPTION ] ) ? wp_unslash( $_POST[ self::OPTION ] ) : null; // phpcs:ignore WordPress.Security.NonceVerification.Missing,WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Shape check only; options.php verifies the nonce and values are validated below. foreach ( Settings_Schema::fields() as $group => $fields ) { if ( ! is_array( $submitted ) || ! isset( $submitted[ $group ] ) || ! is_array( $submitted[ $group ] ) ) { add_settings_error( self::OPTION, 'loginstudio_incomplete', __( 'The Login Brush settings form is incomplete. No changes were saved.', 'login-brush' ) ); return $previous; } } } if ( is_wp_error( $this->migrate( $previous ) ) ) { add_settings_error( self::OPTION, 'loginstudio_schema', __( 'Login Brush settings use an unsupported schema. They have been preserved.', 'login-brush' ) ); return $previous; } if ( is_array( $input ) && array_key_exists( 'schema_version', $input ) && null === $this->version_of( $input ) ) { add_settings_error( self::OPTION, 'loginstudio_version', __( 'Invalid Login Brush schema version.', 'login-brush' ) ); return $previous; } if ( is_array( $input ) && $this->version_of( $input ) > Settings_Schema::VERSION ) { add_settings_error( self::OPTION, 'loginstudio_version', __( 'This Login Brush schema version is not supported.', 'login-brush' ) ); return $previous; } $result = $this->validate( $input ); if ( $result['errors'] ) { add_settings_error( self::OPTION, 'loginstudio_invalid', __( 'Login Brush settings contain invalid values. No changes were saved.', 'login-brush' ) ); return $previous; } return Settings_Schema::compact( $result['settings'] ); } /** * Trusted lifecycle initialization: metadata only, existing values preserved. * Migration writes are restricted to activation/authorized admin flows. * * @return bool|\WP_Error */ public function initialize() { if ( ! current_user_can( self::capability() ) && ! current_user_can( 'activate_plugins' ) && ! current_user_can( 'manage_network_plugins' ) ) { return new \WP_Error( 'loginstudio_forbidden', __( 'You cannot initialize Login Brush settings.', 'login-brush' ) ); } $stored = get_option( self::OPTION, null ); if ( null === $stored ) { return add_option( self::OPTION, array( 'schema_version' => Settings_Schema::VERSION ), '', false ); } $migrated = $this->migrate( $stored ); if ( is_wp_error( $migrated ) ) { return $migrated; } if ( $migrated !== $stored ) { $result = $this->validate( $migrated ); if ( $result['errors'] ) { return new \WP_Error( 'loginstudio_migration_invalid', __( 'Login Brush settings could not be migrated safely.', 'login-brush' ) ); } return update_option( self::OPTION, Settings_Schema::compact( $result['settings'] ), false ); } return true; } /** * Reset service only; Editor::reset verifies the HTTP method and nonce first. * * @return bool|\WP_Error True includes already-default settings. */ public function reset() { if ( ! current_user_can( self::capability() ) ) { return new \WP_Error( 'loginstudio_forbidden', __( 'You cannot reset Login Brush settings.', 'login-brush' ) ); } $stored = get_option( self::OPTION, null ); if ( is_wp_error( $this->migrate( $stored ) ) ) { return new \WP_Error( 'loginstudio_schema', __( 'Unsupported Login Brush settings cannot be reset by this version.', 'login-brush' ) ); } $defaults = Settings_Schema::compact( $this->defaults() ); return $stored === $defaults || update_option( self::OPTION, $defaults, false ); } /** * Report stored and current schema versions separately. * * @return array Current plugin/schema and stored schema versions. */ public function versions() { $this->all(); return array( 'plugin' => LOGINSTUDIO_VERSION, 'schema' => Settings_Schema::VERSION, 'stored_schema' => $this->version_of( $this->stored ), ); } /** * Check schema support before allowing editing or reset. * * @return bool Whether editing the stored schema is safe. */ public function is_supported() { $this->all(); return ! is_wp_error( $this->migrate( $this->stored ) ); } /** Invalidate after Options API writes or site switches. */ public function clear_cache() { $this->cache = null; $this->stored = null; } /** * Initial versionless-to-V1 migration. No separate version option is needed. * * @param mixed $stored Persisted candidate. * @return array|\WP_Error */ private function migrate( $stored ) { if ( null === $stored ) { return array( 'schema_version' => Settings_Schema::VERSION ); } $version = $this->version_of( $stored ); if ( null === $version || $version > Settings_Schema::VERSION ) { return new \WP_Error( 'loginstudio_schema' ); } while ( $version < Settings_Schema::VERSION ) { switch ( $version ) { case 0: $stored['schema_version'] = 1; break; default: return new \WP_Error( 'loginstudio_schema' ); } ++$version; } return $stored; } /** * Validate and retrieve the stored schema version. * * @param mixed $stored Stored candidate. * @return int|null Null indicates corrupt metadata, zero versionless data. */ private function version_of( $stored ) { if ( ! is_array( $stored ) ) { return null === $stored ? 0 : null; } if ( ! array_key_exists( 'schema_version', $stored ) ) { return 0; } $value = $stored['schema_version']; if ( is_string( $value ) && preg_match( '/^(0|[1-9][0-9]*)$/D', $value ) ) { $value = filter_var( $value, FILTER_VALIDATE_INT ); } return is_int( $value ) && $value >= 0 ? $value : null; } }