Make WordPress Core

Changeset 56467


Ignore:
Timestamp:
08/25/2023 03:24:00 AM (11 months ago)
Author:
DrewAPicture
Message:

Introduce a _deprecated_class() function.

Similar to other function in the _deprecated_* series, _deprecated_class() comes with two new hooks: deprecated_class_run and deprecated_class_trigger_error.

Support has also been added for setting class deprecation expectations in tests.

Props jrf, wvega, ohryan.
See #41125.

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.php

    r56414 r56467  
    55975597
    55985598/**
     5599 * Marks a class as deprecated and informs when it has been used.
     5600 *
     5601 * There is a {@see 'deprecated_class_run'} hook that will be called that can be used
     5602 * to get the backtrace up to what file and function called the
     5603 * deprecated class.
     5604 *
     5605 * The current behavior is to trigger a user error if `WP_DEBUG` is true.
     5606 *
     5607 * This function is to be used in the class constructor for every deprecated class.
     5608 * See {@see _deprecated_constructor()} for deprecating PHP4 style constructors.
     5609 *
     5610 * @since 6.4.0
     5611 *
     5612 * @param string $class       The class being instantiated
     5613 * @param string $version     The version of WordPress that deprecated the class.
     5614 * @param string $replacement Optional. The class or function that should have been called.
     5615 *                            Default empty string.
     5616 */
     5617function _deprecated_class( $class, $version, $replacement = '' ) {
     5618
     5619    /**
     5620     * Fires when a deprecated class is called.
     5621     *
     5622     * @since 6.4.0
     5623     *
     5624     * @param string $class       The class being instantiated
     5625     * @param string $replacement The class or function that should have been called.
     5626     * @param string $version     The version of WordPress that deprecated the class.
     5627     */
     5628    do_action( 'deprecated_class_run', $class, $replacement, $version );
     5629
     5630    /**
     5631     * Filters whether to trigger an error for a deprecated class.
     5632     *
     5633     * @since 6.4.0
     5634     *
     5635     * @param bool $trigger Whether to trigger an error for a deprecated class. Default true.
     5636     */
     5637    if ( WP_DEBUG && apply_filters( 'deprecated_class_trigger_error', true ) ) {
     5638        if ( function_exists( '__' ) ) {
     5639            if ( ! is_null( $replacement ) ) {
     5640                /* translators: 1: PHP class name, 2: version number, 3: alternative clas or function name */
     5641                trigger_error( sprintf( __('Class %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.'), $class, $version, $replacement ), E_USER_DEPRECATED );
     5642            } else {
     5643                /* translators: 1: PHP class name, 2: version number */
     5644                trigger_error( sprintf( __('Class %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.'), $class, $version ), E_USER_DEPRECATED );
     5645            }
     5646        } else {
     5647            if ( ! is_null( $replacement ) ) {
     5648                trigger_error( sprintf( 'Class %1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.', $class, $version, $replacement ), E_USER_DEPRECATED );
     5649            } else {
     5650                trigger_error( sprintf( 'Class %1$s is <strong>deprecated</strong> since version %2$s with no alternative available.', $class, $version ), E_USER_DEPRECATED );
     5651            }
     5652        }
     5653    }
     5654}
     5655
     5656/**
    55995657 * Marks a file as deprecated and inform when it has been used.
    56005658 *
  • trunk/tests/phpunit/includes/abstract-testcase.php

    r56421 r56467  
    569569        add_action( 'deprecated_function_run', array( $this, 'deprecated_function_run' ), 10, 3 );
    570570        add_action( 'deprecated_argument_run', array( $this, 'deprecated_function_run' ), 10, 3 );
     571        add_action( 'deprecated_class_run', array( $this, 'deprecated_function_run' ), 10, 3 );
    571572        add_action( 'deprecated_file_included', array( $this, 'deprecated_function_run' ), 10, 4 );
    572573        add_action( 'deprecated_hook_run', array( $this, 'deprecated_function_run' ), 10, 4 );
     
    575576        add_action( 'deprecated_function_trigger_error', '__return_false' );
    576577        add_action( 'deprecated_argument_trigger_error', '__return_false' );
     578        add_action( 'deprecated_class_trigger_error', '__return_false' );
    577579        add_action( 'deprecated_file_trigger_error', '__return_false' );
    578580        add_action( 'deprecated_hook_trigger_error', '__return_false' );
     
    741743                        $message = sprintf(
    742744                            'Function %1$s was called with an argument that is deprecated since version %2$s with no alternative available.',
     745                            $function_name,
     746                            $version
     747                        );
     748                    }
     749                    break;
     750
     751                case 'deprecated_class_run':
     752                    if ( $replacement ) {
     753                        $message = sprintf(
     754                            'Class %1$s is deprecated since version %2$s! Use %3$s instead.',
     755                            $function_name,
     756                            $version,
     757                            $replacement
     758                        );
     759                    } else {
     760                        $message = sprintf(
     761                            'Class %1$s is deprecated since version %2$s with no alternative available.',
    743762                            $function_name,
    744763                            $version
Note: See TracChangeset for help on using the changeset viewer.