WordPress.org

Make WordPress Core

Ticket #4361: functions.diff

File functions.diff, 2.5 KB (added by darkdragon, 12 years ago)

Teaser, for feedback and discussion

  • functions.php

     
    485485                fclose( $fp );
    486486}
    487487
     488/**
     489 * wp_mark_deprecated() - Marks a function as deprecated and informs when it has been used.
     490 *
     491 * There is a hook that will be called that can be used to get the backtrace up to what file
     492 * and function called the deprecated function. That behavior is not defined here, because of
     493 * preformance.
     494 *
     495 * The current behavior is to trigger an user error if WP_DEBUG is defined and is true. In later
     496 * versions, this behavior could be changed to a more reasonable and less drastic approach of
     497 * letting the user know that deprecated functions were used. However, normal usage will NOT
     498 * trigger these errors, so only those that purposefully enable WP_DEBUG will see them.
     499 *
     500 * This function could be used in every place, including hooks that allows for calling the function.
     501 * The common use will be for functions but can be for hooks, parameters, etc that is deprecated.
     502 *
     503 * @link http://trac.wordpress.org/ticket/4361 History of this function
     504 *
     505 * @package WordPress
     506 * @package Debug
     507 * @since 2.4
     508 *
     509 * @uses do_action() Calls 'deprecated_function_run' and passes the function name and what to use instead.
     510 * @uses apply_filters() Calls 'deprecated_function_trigger_error' and expects boolean value of true to do trigger or false to not trigger error.
     511 *
     512 * @param string $used The function that was called
     513 * @param string $seeinstead The function that should have been called
     514 */
     515function wp_mark_deprecated($used, $seeinstead) {
     516        // Allow plugin to overwrite the error => forward thinking
     517        $outputError = true;
     518
     519        // We can't know if another function will trigger this function before plugins.php is included.
     520        // Test anyway. Small performance lost is okay since this function should not be called at all.
     521        if( function_exists('do_action') ) {
     522                do_action('deprecated_function_run', $function, $seeinstead);
     523
     524                // Allow plugin to filter the output error trigger
     525                $outputError = apply_filters( 'deprecated_function_trigger_error', $outputError );
     526        }
     527
     528        if( $outputError && defined('WP_DEBUG') && true === WP_DEBUG )
     529                trigger_error( printf( __("%s is <strong>deprecated</strong>! Use %s instead."), $function, $seeinstead );
     530}
     531
    488532function do_enclose( $content, $post_ID ) {
    489533        global $wpdb;
    490534        include_once( ABSPATH . WPINC . '/class-IXR.php' );