WP_Customize_Header_Image_Setting::sanitize_choice( mixed $value ): array|string|WP_Error|null

Description

Compatibility

Present in every tracked release (6.7.10 to 7.1.3), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$valuemixed

Value to sanitize.

Return value

array|string|WP_Error|null

Sanitized value, or null/WP_Error if invalid.

Performance profile

How much work a call to WP_Customize_Header_Image_Setting::sanitize_choice() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_post().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

8–124

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 154.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

1

1 place in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()one call below WP_Customize_Header_Image_Setting::sanitize_choice()
• querycontent queryget_post()one call below WP_Customize_Header_Image_Setting::sanitize_choice()

Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 113 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Customize_Header_Image_Setting::sanitize_choice() can have, taken from its control-flow graph on PHP 8.5.

Uses · 7

• sanitize_text_field()Sanitizes a string from user input or from the database.
• absint()Converts a value to non-negative integer.
• get_post_mime_type()Retrieves the mime type of an attachment based on the ID.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• sanitize_url()Sanitizes a URL for database or redirect usage.
• __()Retrieves the translation of $text.
• WP_Error::__construct()Initializes the error.

Used by · 1

• WP_Customize_Header_Image_Setting::sanitize()Sanitizes a header value.

Source code

View on Trac ↗View on GitHub ↗

134	private function sanitize_choice( $value ) {135		// Custom_Image_Header::set_header_image() accepts an object in place of an array.136		if ( is_object( $value ) ) {137			$value = (array) $value;138		}139 140		if ( is_string( $value ) ) {141			return sanitize_text_field( $value );142		}143 144		if ( ! is_array( $value ) ) {145			return null;146		}147 148		/*149		 * The sanitized value is assembled member by member rather than filtered down from the150		 * supplied one, so that nothing but the members below can end up in it.151		 */152		$sanitized = array();153 154		if ( isset( $value['attachment_id'] ) ) {155			if ( ! is_scalar( $value['attachment_id'] ) ) {156				return null;157			}158			$attachment_id = absint( $value['attachment_id'] );159 160			/*161			 * A supplied attachment must be an existing image, since its ID is written to postmeta and its162			 * data displayed. Note that an ID of zero must be skipped rather than looked up, as163			 * get_post_mime_type() falls back to the global post when passed an empty value.164			 */165			if ( $attachment_id > 0 ) {166				$mime_type = get_post_mime_type( $attachment_id );167				if ( ! is_string( $mime_type ) || ! str_starts_with( $mime_type, 'image/' ) ) {168					return null;169				}170			}171 172			$sanitized['attachment_id'] = $attachment_id;173		}174 175		if ( isset( $value['url'] ) ) {176			if ( ! is_string( $value['url'] ) ) {177				return null;178			}179			$sanitized['url'] = sanitize_url( $value['url'] );180			if ( '' === $sanitized['url'] ) {181				return new WP_Error( 'invalid_url', __( 'Invalid URL.' ) );182			}183		}184 185		if ( isset( $value['thumbnail_url'] ) ) {186			if ( ! is_string( $value['thumbnail_url'] ) ) {187				return null;188			}189			$sanitized['thumbnail_url'] = sanitize_url( $value['thumbnail_url'] );190			if ( '' === $sanitized['thumbnail_url'] ) {191				return new WP_Error( 'invalid_url', __( 'Invalid URL.' ) );192			}193		}194 195		if ( isset( $value['timestamp'] ) ) {196			if ( ! is_scalar( $value['timestamp'] ) ) {197				return null;198			}199			$sanitized['timestamp'] = absint( $value['timestamp'] );200		}201 202		if ( isset( $value['width'] ) ) {203			if ( ! is_scalar( $value['width'] ) ) {204				return null;205			}206			$sanitized['width'] = absint( $value['width'] );207		}208 209		if ( isset( $value['height'] ) ) {210			if ( ! is_scalar( $value['height'] ) ) {211				return null;212			}213			$sanitized['height'] = absint( $value['height'] );

Changelog

Introduced in 7.1.1. Unchanged from 6.7.10 through 7.1.3.

1. 6.7.10
2. 6.8.11
3. 6.9.10
4. 7.0.7
5. 7.1.3

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.10 tag, from src/wp-includes/customize/class-wp-customize-header-image-setting.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.