WordPress.org
Get WordPress

Make WordPress Core

Changeset 34997


Ignore:
Timestamp:
10/10/2015 01:58:37 AM (11 years ago)
Author:
boonebgorges
Message:

Introduce WP_Term.

get_term() now returns a WP_Term object, instead of a stdClass object.
Cache support and sanitization filters for individual terms are now more
centralized. For example, get_term_by() is able to cast results of its query
to a WP_Term object by passing it through get_term().

The $taxonomy parameter for get_term() is now optional, as terms ought to
be unique to a taxonomy (ie, shared terms no longer exist). In cases where
get_term() detects that the term matching the specified term_id is from the
wrong taxonomy, it checks to see if you've requested a shared term, and if so,
it splits the term. This is used only for fallback purposes.

The elimination of shared terms allows the caching strategy for terms to be
simplified. Individual terms are now cached in a single 'terms' bucket.

Props flixos90, boonebgorges, scribu, dipesh.kakadiya.
See #14162.

Location:
trunk
Files:
1 added
6 edited

Legend:

Unmodified
Added
Removed

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

    r34419 r34997  
    320320 *
    321321 * @since 2.3.0
     322 * @since 4.4.0 The `$category` parameter now also accepts a WP_Term object.
    322323 * @access private
    323324 *
    324  * @param array|object $category Category Row object or array
     325 * @param array|object|WP_Term $category Category Row object or array
    325326 */
    326327function _make_cat_compat( &$category ) {
    327328        if ( is_object( $category ) && ! is_wp_error( $category ) ) {
    328                 $category->cat_ID = &$category->term_id;
    329                 $category->category_count = &$category->count;
    330                 $category->category_description = &$category->description;
    331                 $category->cat_name = &$category->name;
    332                 $category->category_nicename = &$category->slug;
    333                 $category->category_parent = &$category->parent;
     329                $category->cat_ID = $category->term_id;
     330                $category->category_count = $category->count;
     331                $category->category_description = $category->description;
     332                $category->cat_name = $category->name;
     333                $category->category_nicename = $category->slug;
     334                $category->category_parent = $category->parent;
    334335        } elseif ( is_array( $category ) && isset( $category['term_id'] ) ) {
    335336                $category['cat_ID'] = &$category['term_id'];

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

    r34891 r34997  
    709709 *
    710710 * @since 2.3.0
     711 * @since 4.4.0 Converted to return a WP_Term object if `$output` is `OBJECT`.
     712 *              The `$taxonomy` parameter was made optional.
    711713 *
    712714 * @global wpdb $wpdb WordPress database abstraction object.
    713715 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
    714716 *
    715  * @param int|object $term     If integer, will get from database. If object will apply filters and return $term.
    716  * @param string     $taxonomy Taxonomy name that $term is part of.
     717 * @param int|WP_Term|object $term If integer, term data will be fetched from the database, or from the cache if
     718 *                                 available. If stdClass object (as in the results of a database query), will apply
     719 *                                 filters and return a `WP_Term` object corresponding to the `$term` data. If `WP_Term`,
     720 *                                 will return `$term`.
     721 * @param string     $taxonomy Optional. Taxonomy name that $term is part of.
    717722 * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
    718723 * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
    719  * @return object|array|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
    720  * exist then WP_Error will be returned.
    721  */
    722 function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
    723         global $wpdb;
    724 
     724 * @return mixed Type corresponding to `$output` on success or null on failure. When `$output` is `OBJECT`,
     725 *               a WP_Term instance is returned. If taxonomy does not exist then WP_Error will be returned.
     726 */
     727function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
    725728        if ( empty( $term ) ) {
    726729                return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
    727730        }
    728731
    729         if ( ! taxonomy_exists( $taxonomy ) ) {
     732        if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {
    730733                return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
    731734        }
    732735
    733         if ( is_object($term) && empty($term->filter) ) {
    734                 wp_cache_add( $term->term_id, $term, $taxonomy );
     736        if ( $term instanceof WP_Term ) {
    735737                $_term = $term;
     738        } elseif ( is_object( $term ) ) {
     739                if ( empty( $term->filter ) || 'raw' === $term->filter ) {
     740                        $_term = sanitize_term( $term, $taxonomy, 'raw' );
     741                        $_term = new WP_Term( $_term );
     742                } else {
     743                        $_term = WP_Term::get_instance( $term->term_id );
     744                }
    736745        } else {
    737                 if ( is_object($term) )
    738                         $term = $term->term_id;
    739                 if ( !$term = (int) $term )
    740                         return null;
    741                 if ( ! $_term = wp_cache_get( $term, $taxonomy ) ) {
    742                         $_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE tt.taxonomy = %s AND t.term_id = %d LIMIT 1", $taxonomy, $term) );
    743                         if ( ! $_term )
    744                                 return null;
    745                         wp_cache_add( $term, $_term, $taxonomy );
    746                 }
     746                $_term = WP_Term::get_instance( $term );
     747        }
     748
     749        // If `$taxonomy` was provided, make sure it matches the taxonomy of the located term.
     750        if ( $_term && $taxonomy && $taxonomy !== $_term->taxonomy ) {
     751                // If there are two terms with the same ID, split the other one to a new term.
     752                $new_term_id = _split_shared_term( $_term->term_id, $_term->term_taxonomy_id );
     753
     754                // If no split occurred, this is an invalid request.
     755                if ( $new_term_id === $_term->term_id ) {
     756                        return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
     757
     758                // The term has been split. Refetch the term from the proper taxonomy.
     759                } else {
     760                        return get_term( $_term->term_id, $taxonomy, $output, $filter );
     761                }
     762        }
     763
     764        if ( ! $_term ) {
     765                return null;
    747766        }
    748767
    … …  
    751770         *
    752771         * @since 2.3.0
    753          *
    754          * @param int|object $_term    Term object or ID.
    755          * @param string     $taxonomy The taxonomy slug.
     772         * @since 4.4.0 `$_term` can now also be a WP_Term object.
     773         *
     774         * @param int|WP_Term $_term    Term object or ID.
     775         * @param string      $taxonomy The taxonomy slug.
    756776         */
    757777        $_term = apply_filters( 'get_term', $_term, $taxonomy );
    … …  
    764784         *
    765785         * @since 2.3.0
    766          *
    767          * @param int|object $_term    Term object or ID.
    768          * @param string     $taxonomy The taxonomy slug.
     786         * @since 4.4.0 `$_term` can now also be a WP_Term object.
     787         *
     788         * @param int|WP_Term $_term    Term object or ID.
     789         * @param string      $taxonomy The taxonomy slug.
    769790         */
    770791        $_term = apply_filters( "get_$taxonomy", $_term, $taxonomy );
    771         $_term = sanitize_term($_term, $taxonomy, $filter);
    772 
    773         if ( $output == OBJECT ) {
    774                 return $_term;
    775         } elseif ( $output == ARRAY_A ) {
    776                 $__term = get_object_vars($_term);
    777                 return $__term;
     792
     793        // Sanitize term, according to the specified filter.
     794        $_term->filter( $filter );
     795
     796        if ( $output == ARRAY_A ) {
     797                return $_term->to_array();
    778798        } elseif ( $output == ARRAY_N ) {
    779                 $__term = array_values(get_object_vars($_term));
    780                 return $__term;
    781         } else {
    782                 return $_term;
    783         }
     799                return array_values( $_term->to_array() );
     800        }
     801
     802        return $_term;
    784803}
    785804
    … …  
    799818 *
    800819 * @since 2.3.0
    801  * @since 4.4.0 `$taxonomy` is optional if `$field` is 'term_taxonomy_id'.
     820 * @since 4.4.0 `$taxonomy` is optional if `$field` is 'term_taxonomy_id'. Converted to return
     821 *              a WP_Term object if `$output` is `OBJECT`.
    802822 *
    803823 * @global wpdb $wpdb WordPress database abstraction object.
    … …  
    809829 * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
    810830 * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
    811  * @return object|array|null|WP_Error|false Term Row from database.
    812  *                                          Will return false if $taxonomy does not exist or $term was not found.
     831 * @return WP_Term|bool WP_Term instance on success. Will return false if `$taxonomy` does not exist
     832 *                      or `$term` was not found.
    813833 */
    814834function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
    … …  
    823843
    824844        if ( 'slug' == $field ) {
    825                 $field = 't.slug';
     845                $_field = 't.slug';
    826846                $value = sanitize_title($value);
    827847                if ( empty($value) )
    … …  
    830850                // Assume already escaped
    831851                $value = wp_unslash($value);
    832                 $field = 't.name';
     852                $_field = 't.name';
    833853        } elseif ( 'term_taxonomy_id' == $field ) {
    834854                $value = (int) $value;
    835                 $field = 'tt.term_taxonomy_id';
     855                $_field = 'tt.term_taxonomy_id';
    836856
    837857                // No `taxonomy` clause when searching by 'term_taxonomy_id'.
    … …  
    845865        }
    846866
    847         $term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE $field = %s $tax_clause LIMIT 1", $value ) );
     867        $term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE $_field = %s $tax_clause LIMIT 1", $value ) );
    848868        if ( ! $term )
    849869                return false;
    … …  
    854874        }
    855875
    856         wp_cache_add( $term->term_id, $term, $taxonomy );
    857 
    858         /** This filter is documented in wp-includes/taxonomy-functions.php */
    859         $term = apply_filters( 'get_term', $term, $taxonomy );
    860 
    861         /** This filter is documented in wp-includes/taxonomy-functions.php */
    862         $term = apply_filters( "get_$taxonomy", $term, $taxonomy );
    863 
    864         $term = sanitize_term($term, $taxonomy, $filter);
    865 
    866         if ( $output == OBJECT ) {
    867                 return $term;
    868         } elseif ( $output == ARRAY_A ) {
    869                 return get_object_vars($term);
    870         } elseif ( $output == ARRAY_N ) {
    871                 return array_values(get_object_vars($term));
    872         } else {
    873                 return $term;
    874         }
     876        wp_cache_add( $term->term_id, $term, 'terms' );
     877
     878        return get_term( $term, $taxonomy, $output, $filter );
    875879}
    876880
    … …  
    34233427                        $taxonomies[] = $term->taxonomy;
    34243428                        $ids[] = $term->term_id;
    3425                         wp_cache_delete($term->term_id, $term->taxonomy);
     3429                        wp_cache_delete( $term->term_id, 'terms' );
    34263430                }
    34273431                $taxonomies = array_unique($taxonomies);
    … …  
    34303434                foreach ( $taxonomies as $taxonomy ) {
    34313435                        foreach ( $ids as $id ) {
    3432                                 wp_cache_delete($id, $taxonomy);
     3436                                wp_cache_delete( $id, 'terms' );
    34333437                        }
    34343438                }
    … …  
    35533557                        $term_taxonomy = $term->taxonomy;
    35543558
    3555                 wp_cache_add( $term->term_id, $term, $term_taxonomy );
     3559                wp_cache_add( $term->term_id, $term, 'terms' );
    35563560        }
    35573561}

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

    r34404 r34997  
    1111require_once( ABSPATH . WPINC . '/taxonomy-functions.php' );
    1212
     13/** WP_Term class */
     14require_once( ABSPATH . WPINC . '/class-wp-term.php' );
     15
    1316/** WP_Tax_Query class */
    1417require_once( ABSPATH . WPINC . '/class-wp-tax-query.php' );

  • trunk/tests/phpunit/tests/term/cache.php

    r30954 r34997  
    104104
    105105                $term_object = get_term( $term, 'wptests_tax' );
    106                 wp_cache_delete( $term, 'wptests_tax' );
     106                wp_cache_delete( $term, 'terms' );
    107107
    108108                // Affirm that the cache is empty.
    109                 $this->assertEmpty( wp_cache_get( $term, 'wptests_tax' ) );
     109                $this->assertEmpty( wp_cache_get( $term, 'terms' ) );
    110110
    111111                $num_queries = $wpdb->num_queries;
    … …  
    129129                ) );
    130130
    131                 wp_cache_delete( $term, 'wptests_tax' );
     131                wp_cache_delete( $term, 'terms' );
    132132
    133133                // Affirm that the cache is empty.
    134                 $this->assertEmpty( wp_cache_get( $term, 'wptests_tax' ) );
     134                $this->assertEmpty( wp_cache_get( $term, 'terms' ) );
    135135
    136136                $num_queries = $wpdb->num_queries;
    … …  
    138138                // Prime cache.
    139139                $term_object = get_term( $term, 'wptests_tax' );
    140                 $this->assertNotEmpty( wp_cache_get( $term, 'wptests_tax' ) );
     140                $this->assertNotEmpty( wp_cache_get( $term, 'terms' ) );
    141141                $this->assertSame( $num_queries + 1, $wpdb->num_queries );
    142142
    … …  
    156156                ) );
    157157
    158                 wp_cache_delete( $term, 'wptests_tax' );
     158                wp_cache_delete( $term, 'terms' );
    159159
    160160                // Affirm that the cache is empty.
    161                 $this->assertEmpty( wp_cache_get( $term, 'wptests_tax' ) );
     161                $this->assertEmpty( wp_cache_get( $term, 'terms' ) );
    162162
    163163                $num_queries = $wpdb->num_queries;
    … …  
    165165                // Prime cache.
    166166                $term_object = get_term_by( 'id', $term, 'wptests_tax' );
    167                 $this->assertNotEmpty( wp_cache_get( $term, 'wptests_tax' ) );
     167                $this->assertNotEmpty( wp_cache_get( $term, 'terms' ) );
    168168                $this->assertSame( $num_queries + 1, $wpdb->num_queries );
    169169

  • trunk/tests/phpunit/tests/term/getTerm.php

    r34035 r34997  
    3434
    3535                $this->assertSame( $num_queries, $wpdb->num_queries );
    36         }
    37 
    38         public function test_passing_term_object_should_not_skip_database_query_when_filter_property_is_set() {
    39                 global $wpdb;
    40 
    41                 $term = $this->factory->term->create_and_get( array( 'taxonomy' => 'wptests_tax' ) );
    42                 clean_term_cache( $term->term_id, 'wptests_tax' );
    43 
    44                 $num_queries = $wpdb->num_queries;
    45 
    46                 $term_a = get_term( $term, 'wptests_tax' );
    47 
    48                 $this->assertSame( $num_queries + 1, $wpdb->num_queries );
    4936        }
    5037
    … …  
    9986                $this->assertInternalType( 'object', get_term( $t, 'wptests_tax', 'foo' ) );
    10087        }
     88
     89        /**
     90         * @ticket 14162
     91         */
     92        public function test_numeric_properties_should_be_cast_to_ints() {
     93                global $wpdb;
     94
     95                $t = $this->factory->term->create( array( 'taxonomy' => 'wptests_tax' ) );
     96
     97                // Get raw data from the database.
     98                $term_data = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->terms t JOIN $wpdb->term_taxonomy tt ON ( t.term_id = tt.term_id ) WHERE t.term_id = %d", $t ) );
     99
     100                $found = get_term( $term_data );
     101
     102                $this->assertTrue( $found instanceof WP_Term );
     103                $this->assertInternalType( 'int', $found->term_id );
     104                $this->assertInternalType( 'int', $found->term_taxonomy_id );
     105                $this->assertInternalType( 'int', $found->parent );
     106                $this->assertInternalType( 'int', $found->count );
     107                $this->assertInternalType( 'int', $found->term_group );
     108        }
    101109}

  • trunk/tests/phpunit/tests/term/getTermBy.php

    r34679 r34997  
    6060                $this->assertSame( $t, $found->term_id );
    6161        }
     62
     63        /**
     64         * @ticket 14162
     65         */
     66        public function test_should_prime_term_cache() {
     67                global $wpdb;
     68
     69                register_taxonomy( 'wptests_tax', 'post' );
     70                $t = $this->factory->term->create( array(
     71                        'taxonomy' => 'wptests_tax',
     72                        'slug' => 'foo',
     73                ) );
     74
     75                clean_term_cache( $t, 'wptests_tax' );
     76
     77                $num_queries = $wpdb->num_queries;
     78                $found = get_term_by( 'slug', 'foo', 'wptests_tax' );
     79                $num_queries++;
     80
     81                $this->assertTrue( $found instanceof WP_Term );
     82                $this->assertSame( $t, $found->term_id );
     83                $this->assertSame( $num_queries, $wpdb->num_queries );
     84
     85                // Calls to `get_term()` should now hit cache.
     86                $found2 = get_term( $t );
     87                $this->assertSame( $t, $found->term_id );
     88                $this->assertSame( $num_queries, $wpdb->num_queries );
     89        }
    6290}
Note: See TracChangeset for help on using the changeset viewer.