WordPress.org

Make WordPress Core

Ticket #26937: 26937.diff

File 26937.diff, 4.5 KB (added by DrewAPicture, 4 years ago)

Docs fixes

  • src/wp-includes/link-template.php

     
    11481148 * WordPress Adjacent Post API
    11491149 *
    11501150 * Based on the current or specified post, determines either the previous or
    1151  * next post based on the criteria specified. Supports retrieving posts with the
    1152  * same taxonomy terms and posts that lack specific terms.
     1151 * next post based on the criteria specified. Supports retrieving posts with
     1152 * the same taxonomy terms and posts that lack specific terms.
     1153 *
     1154 * @since 3.9.0
     1155 *
     1156 * @package WordPress
     1157 * @subpackage Template
    11531158 */
    11541159class WP_Adjacent_Post {
     1160
     1161        /**
     1162         * Adjacent post object.
     1163         *
     1164         * @since 3.9.0
     1165         * @access public
     1166         * @var null|WP_Adjacent_Post
     1167         */
    11551168        public $adjacent_post = null;
    11561169
     1170        /**
     1171         * Current post object.
     1172         *
     1173         * @since 3.9.0
     1174         * @access protected
     1175         * @var bool|WP_Post
     1176         */
    11571177        protected $current_post   = false;
     1178
     1179        /**
     1180         * 'previous' or 'next' type of adjacent post.
     1181         *
     1182         * @since 3.9.0
     1183         * @access protected
     1184         * @var string
     1185         */
    11581186        protected $adjacent       = 'previous';
     1187
    11591188        protected $taxonomy       = 'category';
     1189
     1190        /**
     1191         * Whether the post should be in a same taxonomy term.
     1192         *
     1193         * @since 3.9.0
     1194         * @access protected
     1195         * @var string
     1196         */
    11601197        protected $in_same_term   = false;
     1198
     1199        /**
     1200         * Excluded term IDs.
     1201         *
     1202         * @since 3.9.0
     1203         * @access protected
     1204         * @var string|array
     1205         */
    11611206        protected $excluded_terms = '';
    11621207
    11631208        /**
     
    11791224        /**
    11801225         * Allow direct access to adjacent post from the class instance itself
    11811226         *
    1182          * @param string $property
     1227         * @param string $property Property to get.
    11831228         * @return mixed String when adjacent post is found and post property exists. Null when no adjacent post is found.
    11841229         */
    11851230        public function __get( $property ) {
     
    13121357         * Apply the deprecated filters to WP_Query's clauses.
    13131358         *
    13141359         * @param array $clauses
    1315          * @uses $this->filter_join_and_where()
    1316          * @uses $this->filter_sort()
    1317          * @filter post_clauses
    13181360         * @return array
    13191361         */
    13201362        public function filter( $clauses ) {
    1321                 // Immediately deregister these legacy filters to avoid modifying
    1322                 // any calls to WP_Query from filter callbacks hooked to WP_Query filters.
     1363                /*
     1364                 * Immediately deregister these legacy filters to avoid modifying
     1365                 * any calls to WP_Query from filter callbacks hooked to WP_Query filters.
     1366                 */
    13231367                remove_filter( 'posts_clauses', array( $this, 'filter' ) );
    13241368
    1325                 // The `join` and `where` filters are identical in their parameters,
    1326                 // so we can use the same approach for both.
     1369                /*
     1370                 * The `join` and `where` filters are identical in their parameters,
     1371                 * so we can use the same approach for both.
     1372                 */
    13271373                foreach ( array( 'join', 'where' ) as $clause ) {
    13281374                        if ( has_filter( 'get_' . $this->adjacent . '_post_' . $clause ) ) {
    13291375                                $clauses[ $clause ] = $this->filter_join_and_where( $clauses[ $clause ], $clause );
    13301376                        }
    13311377                }
    13321378
    1333                 // The legacy `sort` filter combined the ORDER BY and LIMIT clauses,
    1334                 // while `WP_Query` does not, which requires special handling.
     1379                /*
     1380                 * The legacy `sort` filter combined the ORDER BY and LIMIT clauses,
     1381                 * while `WP_Query` does not, which requires special handling.
     1382                 */
    13351383                if ( has_filter( 'get_' . $this->adjacent . '_post_sort' ) ) {
    13361384                        $sort_clauses = $this->filter_sort( $clauses['orderby'], $clauses['limits'] );
    13371385                        $clauses      = array_merge( $clauses, $sort_clauses );
     
    13491397         */
    13501398        protected function filter_join_and_where( $value, $clause ) {
    13511399                /**
     1400                 * @todo Minimal hook docs
    13521401                 * @deprecated 3.9.0
    13531402                 */
    13541403                return apply_filters( 'get_' . $this->adjacent . '_post_' . $clause, $value, $this->in_same_term, $this->excluded_terms );
     
    13771426
    13781427                // Split the string of one or two clauses into their respective array keys
    13791428                if ( false !== $has_order_by && false !== $has_limit ) {
    1380                         // The LIMIT clause cannot appear before the ORDER BY clause in a valid query
    1381                         // However, since the legacy filter would allow a user to invert the order, we maintain that handling so the same errors are triggered.
     1429                        /*
     1430                         * The LIMIT clause cannot appear before the ORDER BY clause in a valid query
     1431                         * However, since the legacy filter would allow a user to invert the order,
     1432                         * we maintain that handling so the same errors are triggered.
     1433                         */
    13821434                        if ( $has_order_by < $has_limit ) {
    13831435                                $orderby = trim( str_ireplace( 'order by', '', substr( $sort, 0, $has_limit ) ) );
    13841436                                $limits  = trim( substr( $sort, $has_limit ) );