WordPress.org
Get WordPress

Make WordPress Core

Changeset 62704


Ignore:
Timestamp:
07/13/2026 07:14:54 AM (8 weeks ago)
Author:
westonruter
Message:

Docs: Add never return types to functions that always terminate.

Documents @return never on 30 functions and methods whose every control-flow path ends in exit, die(), wp_die(), or wp_send_json_*(), so static analysis knows the code following a call to them is unreachable. Native never requires PHP 8.1, so these are PHPDoc-only.

Where terminating depends on a parameter, a conditional @phpstan-return describes each case rather than over-widening to the union of both. The seven wp_die() handlers gain the same conditional wp_die() itself already carries. trackback_response() and wp_protect_special_option() never return for the parameter values that die, while redirect_canonical(), check_admin_referer(), check_ajax_referer(), and get_cli_args() narrow their return types accordingly.

The bottom type never was also incorrectly declared in the return type union for get_cli_args(), so it was removed.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/12488.
Follow-up to r62703, r62178, r62177.

Props westonruter, mukesh27.
See #64896, #64898.

Location:
trunk/src
Files:
20 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/class-custom-background.php

    r62353 r62704  
    570570         *
    571571         * @since 4.1.0
     572         *
     573         * @return never
    572574         */
    573575        public function ajax_background_add() {
    … …  
    613615         * @since 3.4.0
    614616         * @deprecated 3.5.0
     617         *
     618         * @return never
    615619         */
    616620        public function wp_set_background_image() {

  • trunk/src/wp-admin/includes/class-custom-image-header.php

    r62353 r62704  
    13841384         *
    13851385         * @since 3.9.0
     1386         *
     1387         * @return never
    13861388         */
    13871389        public function ajax_header_crop() {
    … …  
    14531455         *
    14541456         * @since 3.9.0
     1457         *
     1458         * @return never
    14551459         */
    14561460        public function ajax_header_add() {
    … …  
    14811485         *
    14821486         * @since 3.9.0
     1487         *
     1488         * @return never
    14831489         */
    14841490        public function ajax_header_remove() {

  • trunk/src/wp-admin/includes/class-wp-importer.php

    r62690 r62704  
    299299 * @param string $param    The parameter name to retrieve.
    300300 * @param bool   $required Optional. Whether the parameter is required. Default false.
    301  * @return string|true|null|never The parameter value or true if found, null otherwise.
    302  *                                The function exits when a required parameter is missing.
     301 * @return string|true|null The parameter value, or true if the parameter was supplied
     302 *                          without a value, or null if it was not supplied at all.
     303 *                          Never returns when `$required` is true and the parameter
     304 *                          is missing, as the function exits instead.
     305 * @phpstan-return ( $required is true ? string|true : string|true|null )
    303306 */
    304307function get_cli_args( $param, $required = false ) {

  • trunk/src/wp-admin/includes/class-wp-list-table.php

    r62491 r62704  
    18441844         *
    18451845         * @since 3.1.0
     1846         *
     1847         * @return never
    18461848         */
    18471849        public function ajax_response() {

  • trunk/src/wp-admin/includes/comment.php

    r62673 r62704  
    295295 *
    296296 * @param string $msg Error Message. Assumed to contain HTML and be sanitized.
     297 * @return never
    297298 */
    298299function comment_footer_die( $msg ) {

  • trunk/src/wp-admin/includes/post.php

    r62550 r62704  
    21842184 *
    21852185 * @param int $post_id Optional. Post ID.
     2186 * @return never
    21862187 */
    21872188function redirect_post( $post_id = 0 ) {

  • trunk/src/wp-admin/includes/theme-install.php

    r57714 r62704  
    252252 *
    253253 * @global WP_Theme_Install_List_Table $wp_list_table
     254 *
     255 * @return never
    254256 */
    255257function install_theme_information() {

  • trunk/src/wp-includes/canonical.php

    r62178 r62704  
    3939 * @param bool   $do_redirect   Optional. Redirect to the new URL.
    4040 * @return string|null The string of the URL, if redirect needed. Never returns if a redirect occurs, depending on $do_redirect.
     41 * @phpstan-return ( $do_redirect is true ? null : string|null )
    4142 */
    4243function redirect_canonical( $requested_url = null, $do_redirect = true ) {

  • trunk/src/wp-includes/class-wp-ajax-response.php

    r54133 r62704  
    149149         *
    150150         * @since 2.1.0
     151         *
     152         * @return never
    151153         */
    152154        public function send() {

  • trunk/src/wp-includes/class-wp-customize-manager.php

    r62489 r62704  
    448448         * @param string|WP_Error $ajax_message Ajax return.
    449449         * @param string          $message      Optional. UI message.
     450         * @return never
    450451         */
    451452        protected function wp_die( $ajax_message, $message = null ) {
    … …  
    24282429         * @since 3.4.0
    24292430         * @since 4.7.0 The semantics of this method have changed to update a changeset, optionally to also change the status and other attributes.
     2431         *
     2432         * @return never
    24302433         */
    24312434        public function save() {
    … …  
    33873390         *
    33883391         * @since 4.9.0
     3392         *
     3393         * @return never
    33893394         */
    33903395        public function handle_override_changeset_lock_request() {
    … …  
    36863691         *
    36873692         * @since 4.2.0
     3693         *
     3694         * @return never
    36883695         */
    36893696        public function refresh_nonces() {
    … …  
    36993706         *
    37003707         * @since 4.9.0
     3708         *
     3709         * @return never
    37013710         */
    37023711        public function handle_dismiss_autosave_or_lock_request() {
    … …  
    58255834         *
    58265835         * @since 4.9.0
     5836         *
     5837         * @return never
    58275838         */
    58285839        public function handle_load_themes_request() {

  • trunk/src/wp-includes/class-wp-customize-nav-menus.php

    r61433 r62704  
    8989         *
    9090         * @since 4.3.0
     91         *
     92         * @return never
    9193         */
    9294        public function ajax_load_available_items() {
    … …  
    314316         *
    315317         * @since 4.3.0
     318         *
     319         * @return never
    316320         */
    317321        public function ajax_search_available_items() {
    … …  
    9961000         *
    9971001         * @since 4.7.0
     1002         *
     1003         * @return never
    9981004         */
    9991005        public function ajax_insert_auto_draft_post() {

  • trunk/src/wp-includes/class-wp-customize-widgets.php

    r62167 r62704  
    16981698         *
    16991699         * @see wp_ajax_save_widget()
     1700         *
     1701         * @return never
    17001702         */
    17011703        public function wp_ajax_update_widget() {

  • trunk/src/wp-includes/class-wp-plugin-dependencies.php

    r62178 r62704  
    434434         *
    435435         * @since 6.5.0
     436         *
     437         * @return never
    436438         */
    437439        public static function check_plugin_dependencies_during_ajax() {

  • trunk/src/wp-includes/functions.php

    r62703 r62704  
    17481748 *
    17491749 * @since 5.4.0
     1750 *
     1751 * @return never
    17501752 */
    17511753function do_favicon() {
    … …  
    37133715 *
    37143716 * @param string $action The nonce action.
     3717 * @return never
    37153718 */
    37163719function wp_nonce_ays( $action ) {
    … …  
    38923895 * @param string          $title   Optional. Error title. Default empty string.
    38933896 * @param string|array    $args    Optional. Arguments to control behavior. Default empty array.
     3897 * @phpstan-return ( $args is array{exit: false} ? void : never )
    38943898 */
    38953899function _default_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    40944098 * @param string       $title   Optional. Error title (unused). Default empty string.
    40954099 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4100 * @phpstan-return ( $args is array{exit: false} ? void : never )
    40964101 */
    40974102function _ajax_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    41364141 * @param string       $title   Optional. Error title. Default empty string.
    41374142 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4143 * @phpstan-return ( $args is array{exit: false} ? void : never )
    41384144 */
    41394145function _json_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    41784184 * @param string       $title   Optional. Error title. Default empty string.
    41794185 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4186 * @phpstan-return ( $args is array{exit: false} ? void : never )
    41804187 */
    41814188function _jsonp_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    42264233 * @param string       $title   Optional. Error title. Default empty string.
    42274234 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4235 * @phpstan-return ( $args is array{exit: false} ? void : never )
    42284236 */
    42294237function _xmlrpc_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    42564264 * @param string       $title   Optional. Error title. Default empty string.
    42574265 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4266 * @phpstan-return ( $args is array{exit: false} ? void : never )
    42584267 */
    42594268function _xml_wp_die_handler( $message, $title = '', $args = array() ) {
    … …  
    43014310 * @param string       $title   Optional. Error title (unused). Default empty string.
    43024311 * @param string|array $args    Optional. Arguments to control behavior. Default empty array.
     4312 * @phpstan-return ( $args is array{exit: false} ? void : never )
    43034313 */
    43044314function _scalar_wp_die_handler( $message = '', $title = '', $args = array() ) {
    … …  
    45654575 * @param int   $status_code Optional. The HTTP status code to output. Default null.
    45664576 * @param int   $flags       Optional. Options to be passed to json_encode(). Default 0.
     4577 * @return never
    45674578 */
    45684579function wp_send_json( $response, $status_code = null, $flags = 0 ) {
    … …  
    46124623 * @param int   $status_code Optional. The HTTP status code to output. Default null.
    46134624 * @param int   $flags       Optional. Options to be passed to json_encode(). Default 0.
     4625 * @return never
    46144626 */
    46154627function wp_send_json_success( $value = null, $status_code = null, $flags = 0 ) {
    … …  
    46394651 * @param int   $status_code Optional. The HTTP status code to output. Default null.
    46404652 * @param int   $flags       Optional. Options to be passed to json_encode(). Default 0.
     4653 * @return never
    46414654 */
    46424655function wp_send_json_error( $value = null, $status_code = null, $flags = 0 ) {

  • trunk/src/wp-includes/ms-deprecated.php

    r61995 r62704  
    8686 * @deprecated 3.0.0 Use wp_die()
    8787 * @see wp_die()
     88 *
     89 * @return never
    8890 */
    8991function graceful_fail( $message ) {
    … …  
    269271 *
    270272 * @param string $url Optional. Redirect URL. Default empty.
     273 * @return never
    271274 */
    272275function wpmu_admin_do_redirect( $url = '' ) {

  • trunk/src/wp-includes/ms-load.php

    r62044 r62704  
    466466 * @param string $domain The requested domain for the error to reference.
    467467 * @param string $path   The requested path for the error to reference.
     468 * @return never
    468469 */
    469470function ms_not_installed( $domain, $path ) {

  • trunk/src/wp-includes/option.php

    r62334 r62704  
    560560 *
    561561 * @param string $option Option name.
     562 * @return void Never returns if `$option` is protected, as the function dies in that case.
     563 * @phpstan-return ( $option is 'alloptions'|'notoptions' ? never : void )
    562564 */
    563565function wp_protect_special_option( $option ) {

  • trunk/src/wp-includes/pluggable.php

    r62590 r62704  
    13681368         * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
    13691369         *                   2 if the nonce is valid and generated between 12-24 hours ago.
    1370          *                   False if the nonce is invalid.
     1370         *                   False if the nonce is invalid. Only possible when `$action` is -1,
     1371         *                   as the function otherwise exits rather than returning false.
     1372         * @phpstan-return ( $action is -1 ? int|false : int )
    13711373         */
    13721374        function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
    … …  
    14131415         * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
    14141416         *                   2 if the nonce is valid and generated between 12-24 hours ago.
    1415          *                   False if the nonce is invalid.
     1417         *                   False if the nonce is invalid. Only possible when `$stop` is false,
     1418         *                   as the function otherwise exits rather than returning false.
     1419         * @phpstan-return ( $stop is true ? int : int|false )
    14161420         */
    14171421        function check_ajax_referer( $action = -1, $query_arg = false, $stop = true ) {

  • trunk/src/wp-includes/sitemaps/class-wp-sitemaps-stylesheet.php

    r56752 r62704  
    2121         *
    2222         * @param string $type Stylesheet type. Either 'sitemap' or 'index'.
     23         * @return never
    2324         */
    2425        public function render_stylesheet( $type ) {

  • trunk/src/wp-trackback.php

    r62414 r62704  
    2525 *
    2626 * @param int|bool $error         Whether there was an error.
    27  *                                Default '0'. Accepts '0' or '1', true or false.
     27 *                                Default 0. Accepts 0 or 1, true or false.
    2828 * @param string   $error_message Error message if an error occurred. Default empty string.
     29 * @return void Never returns if `$error` is truthy, as the function dies after
     30 *              sending the error response.
     31 * @phpstan-return ( $error is 0|false ? void : never )
    2932 */
    3033function trackback_response( $error = 0, $error_message = '' ) {
Note: See TracChangeset for help on using the changeset viewer.