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