[Summary view] [Print] [Text view]

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