WordPress.org
Get WordPress

Making WordPress.org


Ignore:
Timestamp:
09/05/2022 05:14:31 AM (3 years ago)
Author:
dufresnesteven
Message:

wporg-developer: Sync with ​https://github.com/WordPress/wporg-developer/commit/790d402933d2725374de0d19e6bf6a576c8b15d2

File:
1 edited

Legend:

Unmodified
Added
Removed

  • sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

    r11311 r12050  
    114114            // Check if the current page is a reply to a note.
    115115            $reply_id = 0;
    116             if ( isset( $_GET['replytocom'] ) && $_GET['replytocom'] ) {       
     116            if ( isset( $_GET['replytocom'] ) && $_GET['replytocom'] ) {
    117117                /* Javascript uses preventDefault() when clicking links with '?replytocom={comment_ID}'
    118118                 * We assume Javascript is disabled when visiting a page with this query var.
    … …  
    176176            $can_user_post_note = DevHub\can_user_post_note( true, get_the_ID() );
    177177            $is_user_verified   = $is_user_logged_in && $can_user_post_note;
    178        
     178
    179179            $args['updated_note'] = 0;
    180180            if ( isset( $_GET['updated-note'] ) && $_GET['updated-note'] ) {
    … …  
    621621     */
    622622    function get_site_section_url() {
    623         $parts = explode( '/', $GLOBALS['wp']->request );
    624         switch ( $parts[0] ) {
    625             case 'reference':
    626             case 'plugins':
    627             case 'themes':
    628                 return home_url( '/' . $parts[0] . '/' );
    629             case 'cli':
    630                 return home_url( '/cli/commands/' );
    631             default:
    632                 return home_url( '/' );
    633         }
     623        return home_url( '/' );
    634624    }
    635625
    … …  
    645635            case 'resource':
    646636                return sprintf( __( 'Developer Resources: %s', 'wporg' ), get_the_title() );
    647             case 'reference':
    648                 return __( 'Code Reference', 'wporg' );
    649             case 'plugins':
    650                 return __( 'Plugin Handbook', 'wporg' );
    651             case 'themes':
    652                 return __( 'Theme Handbook', 'wporg' );
    653             case 'apis':
    654                 return __( 'Common APIs Handbook', 'wporg' );
    655             case 'block-editor':
    656                 return __( 'Block Editor Handbook', 'wporg' );
    657             case 'cli':
    658                 return __( 'WP-CLI Commands', 'wporg' );
    659             case 'coding-standards':
    660                 return __( 'Coding Standards Handbook', 'wporg' );
    661             case 'rest-api':
    662                 return __( 'REST API Handbook', 'wporg' );
    663637            default:
     638                if( is_page( 'reference' ) ) {
     639                    return __( 'Code Reference', 'wporg' );
     640                }
     641
    664642                return __( 'Developer Resources', 'wporg' );
    665643        }
    … …  
    685663        }
    686664        return $name;
     665    }
     666
     667    /**
     668     * Returns the hook string.
     669     *
     670     * @param int $post_id
     671     *
     672     * @return string
     673     */
     674    function get_hook_type_name( $post_id ) {
     675        $hook_type = get_post_meta( $post_id, '_wp-parser_hook_type', true );
     676        if ( false !== strpos( $hook_type, 'action' ) ) {
     677            if ( 'action_reference' === $hook_type ) {
     678                $hook_type = 'do_action_ref_array';
     679            } elseif ( 'action_deprecated' === $hook_type ) {
     680                $hook_type = 'do_action_deprecated';
     681            } else {
     682                $hook_type = 'do_action';
     683            }
     684        } else {
     685            if ( 'filter_reference' === $hook_type ) {
     686                $hook_type = 'apply_filters_ref_array';
     687            } elseif ( 'filter_deprecated' === $hook_type ) {
     688                $hook_type = 'apply_filters_deprecated';
     689            } else {
     690                $hook_type = 'apply_filters';
     691            }
     692        }
     693
     694        return $hook_type;
    687695    }
    688696
    … …  
    708716
    709717        if ( 'wp-parser-class' === get_post_type( $post_id ) ) {
    710             return $signature;
     718            return '<span class="keyword">class</span> ' . $signature . ' {}';
    711719        }
    712720
    … …  
    726734            }
    727735
    728             $hook_type = get_post_meta( $post_id, '_wp-parser_hook_type', true );
    729             if ( false !== strpos( $hook_type, 'action' ) ) {
    730                 if ( 'action_reference' === $hook_type ) {
    731                     $hook_type = 'do_action_ref_array';
    732                 } elseif ( 'action_deprecated' === $hook_type ) {
    733                     $hook_type = 'do_action_deprecated';
    734                 } else {
    735                     $hook_type = 'do_action';
    736                 }
    737             } else {
    738                 if ( 'filter_reference' === $hook_type ) {
    739                     $hook_type = 'apply_filters_ref_array';
    740                 } elseif ( 'filter_deprecated' === $hook_type ) {
    741                     $hook_type = 'apply_filters_deprecated';
    742                 } else {
    743                     $hook_type = 'apply_filters';
    744                 }
    745             }
     736            $hook_type = get_hook_type_name( $post_id );
    746737
    747738            $delimiter = false !== strpos( $signature, '$' ) ? '"' : "'";
    … …  
    783774        $signature .= ')';
    784775
     776        $return = get_return( $post_id, false );
     777        if ( $return ) {
     778            $signature .= ': ' . $return;
     779        }
     780
    785781        return wp_kses_post( $signature );
    786782    }
    … …  
    805801            $encountered_optional = false;
    806802            foreach ( $tags as $tag ) {
    807                 // Fix unintended markup introduced by parser.
    808                 $tag = str_replace( array( '<strong>', '</strong>' ), '__', $tag );
    809 
    810803                if ( ! empty( $tag['name'] ) && 'param' == $tag['name'] ) {
    811804                    $params[ $tag['variable'] ] = $tag;
    … …  
    872865                    }
    873866                }
    874 
    875867            }
    876868        }
    … …  
    878870        return $params;
    879871    }
     872
     873    /**
     874     * Recurse through parameters that referer to arguments in other functions or methods, and find the innermost parameter description.
     875     * For example the description for the wp_count_terms( $args ) parameter refers to get_terms( $args ) which in turn refers to WP_Term_Query::__construct( $query ).
     876     * Given the wp_count_terms( $args ) parameter, this will find and return the one for WP_Term_Query::__construct( $query ).
     877     *
     878     * @param array $param A single parameter array as found in `_wp-parser_args` postmeta.
     879     * @param int   $recursion_limit Maximum number of levels to recurse through.
     880     *
     881     * @return array|null
     882     */
     883
     884    function get_param_reference( $param, $recursion_limit = 3 ) {
     885        if ( $recursion_limit > 0 && preg_match_all( '#rel="(function|method)">([^<>()]+)[(][)]</a>#', $param[ 'content' ], $matches, PREG_SET_ORDER ) ) {
     886            foreach ( $matches as $match ) {
     887                if ( $_post = get_page_by_title( $match[2], OBJECT, 'wp-parser-' . $match[1] ) ) {
     888                    if ( $_params = get_params( $_post->ID ) ) {
     889
     890                        $arg_names_to_try = array_unique([
     891                            $param['variable'], // An exact match for the name eg $args
     892                            '$args',
     893                            '$query', // For example get_terms( $args ) -> WP_Term_Query::__construct( $query )
     894                        ]);
     895
     896                        foreach ( $arg_names_to_try as $variable_name ) {
     897                            if ( isset( $_params[ $variable_name ] ) ) {
     898                                // Sometimes the referenced doc page has another level of indirection!
     899                                $recurse = get_param_reference( $_params[ $variable_name ], $recursion_limit - 1 );
     900                                if ( $recurse ) {
     901                                    $recurse[ 'parent' ] = $_post->post_title;
     902                                    $recurse[ 'parent_var' ] = $variable_name;
     903                                    return $recurse;
     904                                } else {
     905                                    $result = $_params[ $variable_name ];
     906                                    $result[ 'parent' ] = $_post->post_title;
     907                                    $result[ 'parent_var' ] = $variable_name;
     908                                    return $result;
     909                                }
     910                            }
     911                        }
     912                    }
     913                }
     914            }
     915        }
     916
     917        return null;
     918    }
     919
    880920
    881921    /**
    … …  
    916956     * @return string
    917957     */
    918     function get_return( $post_id = null ) {
     958    function get_return( $post_id = null, $include_description = true ) {
    919959
    920960        if ( empty( $post_id ) ) {
    … …  
    935975        $type        = apply_filters( 'devhub-function-return-type', $type, $post_id );
    936976
    937         return "<span class='return-type'>({$type})</span> $description";
     977        if ( $include_description ) {
     978            return "<span class='return-type'>{$type}</span> $description";
     979        } else {
     980            return "<span class='return-type'>{$type}</span>";
     981        }
    938982    }
    939983
    … …  
    12461290     */
    12471291    function post_type_has_uses_info( $post_type = null ) {
     1292        $post_type            = $post_type ? $post_type : get_post_type();
     1293        $post_types_with_uses = array( 'wp-parser-function', 'wp-parser-method', 'wp-parser-class' );
     1294
     1295        return in_array( $post_type, $post_types_with_uses );
     1296    }
     1297
     1298    /**
     1299     * Does the post type support hooks information?
     1300     *
     1301     * @param string $post_type Optional. The post type name. If blank, assumes current post type.
     1302     *
     1303     * @return boolean
     1304     */
     1305    function post_type_has_hooks_info( $post_type = null ) {
    12481306        $post_type             = $post_type ? $post_type : get_post_type();
    1249         $post_types_with_uses  = array( 'wp-parser-function', 'wp-parser-method', 'wp-parser-class' );
    1250 
    1251         return in_array( $post_type, $post_types_with_uses );
     1307        $post_types_with_hooks = array( 'wp-parser-function', 'wp-parser-method' );
     1308
     1309        return in_array( $post_type, $post_types_with_hooks );
    12521310    }
    12531311
    … …  
    12731331            return $connected;
    12741332        } elseif ( 'wp-parser-function' === $post_type ) {
    1275             $connection_types = array( 'functions_to_functions', 'functions_to_methods', 'functions_to_hooks' );
     1333            $connection_types = array( 'functions_to_functions', 'functions_to_methods' );
    12761334        } else {
    1277             $connection_types = array( 'methods_to_functions', 'methods_to_methods', 'methods_to_hooks' );
     1335            $connection_types = array( 'methods_to_functions', 'methods_to_methods' );
    12781336        }
    12791337
    12801338        $connected = new \WP_Query( array(
    1281             'post_type'           => array( 'wp-parser-function', 'wp-parser-method', 'wp-parser-hook' ),
     1339            'post_type'           => array( 'wp-parser-function', 'wp-parser-method' ),
    12821340            'connected_type'      => $connection_types,
    1283             'connected_direction' => array( 'from', 'from', 'from' ),
     1341            'connected_direction' => array( 'from', 'from' ),
     1342            'connected_items'     => $post_id,
     1343            'nopaging'            => true,
     1344        ) );
     1345
     1346        return $connected;
     1347    }
     1348
     1349    /**
     1350     * Retrieves a WP_Query object for the hook posts that the current post is linked to.
     1351     *
     1352     * @param int|WP_Post|null $post Optional. Post ID or post object. Default is global $post.
     1353     * @return WP_Query|null   The WP_Query if the post's post type supports 'uses', null otherwise.
     1354     */
     1355    function get_hooks( $post = null ) {
     1356        $post_id   = get_post_field( 'ID', $post );
     1357        $post_type = get_post_type( $post );
     1358
     1359        if ( 'wp-parser-function' === $post_type ) {
     1360            $connection_types = array( 'functions_to_hooks' );
     1361        } else {
     1362            $connection_types = array( 'methods_to_hooks' );
     1363        }
     1364
     1365        $connected = new \WP_Query( array(
     1366            'post_type'           => 'wp-parser-hook',
     1367            'connected_type'      => $connection_types,
     1368            'connected_direction' => array( 'from' ),
    12841369            'connected_items'     => $post_id,
    12851370            'nopaging'            => true,
    … …  
    13371422
    13381423    /**
     1424     * Find functions & methods that are often used by other functions and methods.
     1425     */
     1426    function _get_functions_to_exclude_from_uses() {
     1427        global $wpdb;
     1428
     1429        $ids = get_transient( __METHOD__ );
     1430        if ( $ids ) {
     1431            return $ids;
     1432        }
     1433
     1434        $ids = $wpdb->get_col(
     1435            "SELECT p2p_to
     1436            FROM {$wpdb->p2p} p2p
     1437            WHERE p2p_type IN ( 'methods_to_functions', 'functions_to_functions', 'methods_to_methods', 'functions_to_methods' )
     1438            GROUP BY p2p_to
     1439            HAVING COUNT(*) > 50"
     1440        );
     1441
     1442        set_transient( __METHOD__, $ids, DAY_IN_SECONDS );
     1443
     1444        return $ids;
     1445    }
     1446
     1447    /**
     1448     * Rearrange the results of get_uses() so that frequent functions are pushed to the bottom.
     1449     * Sorts the array in-place.
     1450     *
     1451     * @return int The number of infrequent items in the list (ie the cutoff point for show/hide).
     1452     */
     1453    function split_uses_by_frequent_funcs( &$posts ) {
     1454
     1455        $frequent_funcs = _get_functions_to_exclude_from_uses();
     1456
     1457        // Sort the posts array so frequently used functions are at the end
     1458        usort( $posts, function( $a, $b ) use ( $frequent_funcs ) {
     1459            return (int) in_array( $a->ID, $frequent_funcs ) - (int) in_array( $b->ID, $frequent_funcs );
     1460        } );
     1461
     1462        $infrequent_count = 0;
     1463        foreach ( $posts as $i => $post ) {
     1464            if ( in_array( $post->ID, $frequent_funcs ) ) {
     1465                break;
     1466            }
     1467            $infrequent_count = $i + 1;
     1468        }
     1469
     1470        return $infrequent_count;
     1471    }
     1472
     1473    /**
    13391474     * Returns the array of post types that have source code.
    13401475     *
    … …  
    13421477     */
    13431478    function get_post_types_with_source_code() {
    1344         return array( 'wp-parser-class', 'wp-parser-method', 'wp-parser-function' );
     1479        return array( 'wp-parser-class', 'wp-parser-method', 'wp-parser-function', 'wp-parser-hook' );
    13451480    }
    13461481
    … …  
    14281563            }
    14291564            fclose( $handle );
     1565        }
     1566
     1567        // Trim leading whitespace.
     1568        if ( preg_match_all( "!^([\t ]*).+$!m", $source_code, $m ) ) {
     1569            $strip_prefix = min( array_map( 'strlen', $m[1] ) );
     1570            if ( $strip_prefix ) {
     1571                $source_code = preg_replace( "!^[\t ]{" . $strip_prefix . "}!m", '$1', $source_code );
     1572            }
    14301573        }
    14311574
    … …  
    15941737        $description = $post->post_content;
    15951738
     1739        // Replace code blocks generated by Markdown with wp:code blocks.
     1740        $description = str_replace( '<pre><code>', '[code lang="php"]', $description );
     1741        $description = str_replace( '</code></pre>', '[/code]', $description );
     1742
    15961743        if ( $description ) {
    15971744            $description = apply_filters( 'the_content', apply_filters( 'get_the_content' , $description ) );
    … …  
    16241771        $taxonomies = array( 'wp-parser-since', 'wp-parser-package', 'wp-parser-source-file' );
    16251772
    1626         return ! ( is_search() || is_404() ) && ( is_singular( $post_types ) || is_post_type_archive( $post_types ) || is_tax( $taxonomies ) );
     1773        return ! ( is_search() || is_404() ) && ( is_singular( $post_types ) || is_post_type_archive( $post_types ) || is_tax( $taxonomies ) || is_page( 'reference' ) );
     1774    }
     1775
     1776    /**
     1777     * Should the search bar filters be shown?
     1778     *
     1779     * @return bool True if search bar filters should be shown.
     1780     */
     1781    function should_show_search_filters() {
     1782        $is_handbook = $GLOBALS['wp_query']->is_handbook;
     1783        return ( is_page( 'reference' ) || is_search() ) && ! $is_handbook;
    16271784    }
    16281785
    … …  
    18592016            'return',
    18602017            'explanation',
     2018            'methods',
    18612019            'source',
     2020            'hooks',
    18622021            'related',
    1863             'methods',
    18642022            'changelog',
    18652023            'notes'
Note: See TracChangeset for help on using the changeset viewer.