_deprecated_function( string $function_name, string $version, string $replacement = '' )

Description

Compatibility

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

Parameters

$function_namestring

The function that was called.

$versionstring

The version of WordPress that deprecated the function.

$replacementstringoptional

The function that should have been called. Default empty string.Default: ''

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

function acme_get_product_price( $post_id ) {
	_deprecated_function( __FUNCTION__, '7.1.0', 'get_post_meta()' );
	return get_post_meta( $post_id, 'price', true );
}

$price = acme_get_product_price( 2 );
echo esc_html( 'Price for post 2 via deprecated helper: ' . $price );

add_action( 'deprecated_function_run', function( $function_name, $replacement, $version ) {
	printf(
		'Logged deprecated call: %s (deprecated in %s, replacement: %s)',
		esc_html( $function_name ),
		esc_html( $version ),
		esc_html( $replacement ? $replacement : 'none' )
	);
} );

function acme_legacy_json_encode( $data ) {
	_deprecated_function( __FUNCTION__, '7.1.0', 'wp_json_encode()' );
	return wp_json_encode( $data );
}

$json = acme_legacy_json_encode( array( 'post_id' => 1 ) );
echo '<br>Encoded: ' . esc_html( $json );

Common problems and fixes · 4

• Why doesn't calling _deprecated_function() show any warning on my site?
• Does _deprecated_function() automatically call the replacement function for me?
• How do I silence deprecated-function notices from a third-party plugin without editing its code?
• Can I still detect deprecated calls when WP_DEBUG is off in production?

Alternatives and related functions

_deprecated_argument

When a function or method still exists but one of its parameters or an accepted value has been dropped.

_deprecated_class

When an entire class, rather than a single function, has been replaced or removed.

_deprecated_hook

When a filter or action itself is being retired instead of a callable function.

_doing_it_wrong

When the function is still current but is being called in an incorrect way, rather than being obsolete.

Performance profile

How much work a call to _deprecated_function() 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

Trivial

Touches nothing outside its own arguments.

Scaling

Constant

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

Instructions

12–38

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

Plugin surface

2 hooks

Third-party callbacks on 'deprecated_function_run', 'deprecated_function_trigger_error' run inside this call, and their cost is not bounded by anything here.

Called by

50

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

What it touches

• hookthird-party callbacksdo_action()called directly

Further down the call graph this can also reach query, 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 · 4 distinct outcomes

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

Hooks and filters fired · 2

2 hooks fire while _deprecated_function() runs, in this order:

1. 1
   do_action( deprecated_function_run )actionline 5535 (+11 into the body)

   Fires when a deprecated function is called.

2. 2
   apply_filters( deprecated_function_trigger_error )filterline 5544 (+20 into the body)

   Filters whether to trigger an error for deprecated functions.

Uses · 4

• do_action()Calls the callback functions that have been added to an action hook.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• __()Retrieves the translation of $text.
• wp_trigger_error()Generates a user-level error/warning/notice/deprecation message.

Used by · 50

• Custom_Image_Header::create_attachment_object()Creates an attachment 'object'.
• Services_JSON::__construct()constructs a new JSON instance
• Services_JSON::_encode()PRIVATE CODE that does the work of encodes an arbitrary variable into JSON format
• Services_JSON::decode()decodes a JSON string into appropriate variable
• Services_JSON::encode()encodes an arbitrary variable into JSON format (and sends JSON Header)
• Services_JSON::encodeUnsafe()encodes an arbitrary variable into JSON format without JSON Header - warning - may allow XSS!!!!)
• Services_JSON::isError()
• Services_JSON::name_value()array-walking function for use in generating JSON-formatted name-value pairs
• Services_JSON::reduce_string()reduce a string by removing leading and trailing comments and whitespace
• Services_JSON::strlen8()Calculates length of string in bytes
• Services_JSON::substr8()Returns part of a string, interpreting $start and $length as number of bytes.
• Services_JSON::utf162utf8()convert a string from one UTF-16 char to one UTF-8 char

Source code

View on Trac ↗View on GitHub ↗

5524function _deprecated_function( $function_name, $version, $replacement = '' ) {5525 5526	/**5527	 * Fires when a deprecated function is called.5528	 *5529	 * @since 2.5.05530	 *5531	 * @param string $function_name The function that was called.5532	 * @param string $replacement   The function that should have been called.5533	 * @param string $version       The version of WordPress that deprecated the function.5534	 */5535	do_action( 'deprecated_function_run', $function_name, $replacement, $version );5536 5537	/**5538	 * Filters whether to trigger an error for deprecated functions.5539	 *5540	 * @since 2.5.05541	 *5542	 * @param bool $trigger Whether to trigger the error for deprecated functions. Default true.5543	 */5544	if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {5545		if ( function_exists( '__' ) ) {5546			if ( $replacement ) {5547				$message = sprintf(5548					/* translators: 1: PHP function name, 2: Version number, 3: Alternative function name. */5549					__( 'Function %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ),5550					$function_name,5551					$version,5552					$replacement5553				);5554			} else {5555				$message = sprintf(5556					/* translators: 1: PHP function name, 2: Version number. */5557					__( 'Function %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ),5558					$function_name,5559					$version5560				);5561			}5562		} else {5563			if ( $replacement ) {5564				$message = sprintf(5565					'Function %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.',5566					$function_name,5567					$version,5568					$replacement5569				);5570			} else {5571				$message = sprintf(5572					'Function %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.',5573					$function_name,5574					$version5575				);5576			}5577		}5578 5579		wp_trigger_error( '', $message, E_USER_DEPRECATED );5580	}5581}

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

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

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 tag, from src/wp-includes/functions.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.