wp-includes/class-wp-term.php

   1 <?php
   2 /**
   3  * Taxonomy API: WP_Term class
   4  *
   5  * @package WordPress
   6  * @subpackage Taxonomy
   7  * @since 4.4.0
   8  */
   9
  10 /**
  11  * Core class used to implement the WP_Term object.
  12  *
  13  * @since 4.4.0
  14  */
  15 final class WP_Term {
  16
  17         /**
  18          * Term ID.
  19          *
  20          * @since 4.4.0
  21          * @access public
  22          * @var int
  23          */
  24         public $term_id;
  25
  26         /**
  27          * The term's name.
  28          *
  29          * @since 4.4.0
  30          * @access public
  31          * @var string
  32          */
  33         public $name = '';
  34
  35         /**
  36          * The term's slug.
  37          *
  38          * @since 4.4.0
  39          * @access public
  40          * @var string
  41          */
  42         public $slug = '';
  43
  44         /**
  45          * The term's term_group.
  46          *
  47          * @since 4.4.0
  48          * @access public
  49          * @var string
  50          */
  51         public $term_group = '';
  52
  53         /**
  54          * Term Taxonomy ID.
  55          *
  56          * @since 4.4.0
  57          * @access public
  58          * @var int
  59          */
  60         public $term_taxonomy_id = 0;
  61
  62         /**
  63          * The term's taxonomy name.
  64          *
  65          * @since 4.4.0
  66          * @access public
  67          * @var string
  68          */
  69         public $taxonomy = '';
  70
  71         /**
  72          * The term's description.
  73          *
  74          * @since 4.4.0
  75          * @access public
  76          * @var string
  77          */
  78         public $description = '';
  79
  80         /**
  81          * ID of a term's parent term.
  82          *
  83          * @since 4.4.0
  84          * @access public
  85          * @var int
  86          */
  87         public $parent = 0;
  88
  89         /**
  90          * Cached object count for this term.
  91          *
  92          * @since 4.4.0
  93          * @access public
  94          * @var int
  95          */
  96         public $count = 0;
  97
  98         /**
  99          * Stores the term object's sanitization level.
 100          *
 101          * Does not correspond to a database field.
 102          *
 103          * @since 4.4.0
 104          * @access public
 105          * @var string
 106          */
 107         public $filter = 'raw';
 108
 109         /**
 110          * Retrieve WP_Term instance.
 111          *
 112          * @since 4.4.0
 113          * @access public
 114          * @static
 115          *
 116          * @global wpdb $wpdb WordPress database abstraction object.
 117          *
 118          * @param int    $term_id  Term ID.
 119          * @param string $taxonomy Optional. Limit matched terms to those matching `$taxonomy`. Only used for
 120          *                         disambiguating potentially shared terms.
 121          * @return WP_Term|WP_Error|false Term object, if found. WP_Error if `$term_id` is shared between taxonomies and
 122          *                                there's insufficient data to distinguish which term is intended.
 123          *                                False for other failures.
 124          */
 125         public static function get_instance( $term_id, $taxonomy = null ) {
 126                 global $wpdb;
 127
 128                 if ( ! is_numeric( $term_id ) || $term_id != floor( $term_id ) || ! $term_id ) {
 129                         return false;
 130                 }
 131
 132                 $term_id = (int) $term_id;
 133
 134                 $_term = wp_cache_get( $term_id, 'terms' );
 135
 136                 // If there isn't a cached version, hit the database.
 137                 if ( ! $_term || ( $taxonomy && $taxonomy !== $_term->taxonomy ) ) {
 138                         // Grab all matching terms, in case any are shared between taxonomies.
 139                         $terms = $wpdb->get_results( $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 t.term_id = %d", $term_id ) );
 140                         if ( ! $terms ) {
 141                                 return false;
 142                         }
 143
 144                         // If a taxonomy was specified, find a match.
 145                         if ( $taxonomy ) {
 146                                 foreach ( $terms as $match ) {
 147                                         if ( $taxonomy === $match->taxonomy ) {
 148                                                 $_term = $match;
 149                                                 break;
 150                                         }
 151                                 }
 152
 153                         // If only one match was found, it's the one we want.
 154                         } elseif ( 1 === count( $terms ) ) {
 155                                 $_term = reset( $terms );
 156
 157                         // Otherwise, the term must be shared between taxonomies.
 158                         } else {
 159                                 // If the term is shared only with invalid taxonomies, return the one valid term.
 160                                 foreach ( $terms as $t ) {
 161                                         if ( ! taxonomy_exists( $t->taxonomy ) ) {
 162                                                 continue;
 163                                         }
 164
 165                                         // Only hit if we've already identified a term in a valid taxonomy.
 166                                         if ( $_term ) {
 167                                                 return new WP_Error( 'ambiguous_term_id', __( 'Term ID is shared between multiple taxonomies' ), $term_id );
 168                                         }
 169
 170                                         $_term = $t;
 171                                 }
 172                         }
 173
 174                         if ( ! $_term ) {
 175                                 return false;
 176                         }
 177
 178                         // Don't return terms from invalid taxonomies.
 179                         if ( ! taxonomy_exists( $_term->taxonomy ) ) {
 180                                 return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
 181                         }
 182
 183                         $_term = sanitize_term( $_term, $_term->taxonomy, 'raw' );
 184
 185                         // Don't cache terms that are shared between taxonomies.
 186                         if ( 1 === count( $terms ) ) {
 187                                 wp_cache_add( $term_id, $_term, 'terms' );
 188                         }
 189                 }
 190
 191                 $term_obj = new WP_Term( $_term );
 192                 $term_obj->filter( $term_obj->filter );
 193
 194                 return $term_obj;
 195         }
 196
 197         /**
 198          * Constructor.
 199          *
 200          * @since 4.4.0
 201          * @access public
 202          *
 203          * @param WP_Term|object $term Term object.
 204          */
 205         public function __construct( $term ) {
 206                 foreach ( get_object_vars( $term ) as $key => $value ) {
 207                         $this->$key = $value;
 208                 }
 209         }
 210
 211         /**
 212          * Sanitizes term fields, according to the filter type provided.
 213          *
 214          * @since 4.4.0
 215          * @access public
 216          *
 217          * @param string $filter Filter context. Accepts 'edit', 'db', 'display', 'attribute', 'js', 'raw'.
 218          */
 219         public function filter( $filter ) {
 220                 sanitize_term( $this, $this->taxonomy, $filter );
 221         }
 222
 223         /**
 224          * Converts an object to array.
 225          *
 226          * @since 4.4.0
 227          * @access public
 228          *
 229          * @return array Object as array.
 230          */
 231         public function to_array() {
 232                 return get_object_vars( $this );
 233         }
 234
 235         /**
 236          * Getter.
 237          *
 238          * @since 4.4.0
 239          * @access public
 240          *
 241          * @param string $key Property to get.
 242          * @return mixed Property value.
 243          */
 244         public function __get( $key ) {
 245                 switch ( $key ) {
 246                         case 'data' :
 247                                 $data = new stdClass();
 248                                 $columns = array( 'term_id', 'name', 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', 'parent', 'count' );
 249                                 foreach ( $columns as $column ) {
 250                                         $data->{$column} = isset( $this->{$column} ) ? $this->{$column} : null;
 251                                 }
 252
 253                                 return sanitize_term( $data, $data->taxonomy, 'raw' );
 254                 }
 255         }
 256 }