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]
 18final 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	 *
107	 * @global wpdb $wpdb WordPress database abstraction object.
108	 *
109	 * @param int    $term_id  Term ID.
110	 * @param string $taxonomy Optional. Limit matched terms to those matching `$taxonomy`. Only used for
111	 *                         disambiguating potentially shared terms.
112	 * @return WP_Term|WP_Error|false Term object, if found. WP_Error if `$term_id` is shared between taxonomies and
113	 *                                there's insufficient data to distinguish which term is intended.
114	 *                                False for other failures.
115	 */
116	public static function get_instance( $term_id, $taxonomy = null ) {
117		global $wpdb;
118
119		$term_id = (int) $term_id;
120		if ( ! $term_id ) {
121			return false;
122		}
123
124		$_term = wp_cache_get( $term_id, 'terms' );
125
126		// If there isn't a cached version, hit the database.
127		if ( ! $_term || ( $taxonomy && $taxonomy !== $_term->taxonomy ) ) {
128			// Any term found in the cache is not a match, so don't use it.
129			$_term = false;
130
131			// Grab all matching terms, in case any are shared between taxonomies.
132			$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 ) );
133			if ( ! $terms ) {
134				return false;
135			}
136
137			// If a taxonomy was specified, find a match.
138			if ( $taxonomy ) {
139				foreach ( $terms as $match ) {
140					if ( $taxonomy === $match->taxonomy ) {
141						$_term = $match;
142						break;
143					}
144				}
145
146				// If only one match was found, it's the one we want.
147			} elseif ( 1 === count( $terms ) ) {
148				$_term = reset( $terms );
149
150				// Otherwise, the term must be shared between taxonomies.
151			} else {
152				// If the term is shared only with invalid taxonomies, return the one valid term.
153				foreach ( $terms as $t ) {
154					if ( ! taxonomy_exists( $t->taxonomy ) ) {
155						continue;
156					}
157
158					// Only hit if we've already identified a term in a valid taxonomy.
159					if ( $_term ) {
160						return new WP_Error( 'ambiguous_term_id', __( 'Term ID is shared between multiple taxonomies' ), $term_id );
161					}
162
163					$_term = $t;
164				}
165			}
166
167			if ( ! $_term ) {
168				return false;
169			}
170
171			// Don't return terms from invalid taxonomies.
172			if ( ! taxonomy_exists( $_term->taxonomy ) ) {
173				return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
174			}
175
176			$_term = sanitize_term( $_term, $_term->taxonomy, 'raw' );
177
178			// Don't cache terms that are shared between taxonomies.
179			if ( 1 === count( $terms ) ) {
180				wp_cache_add( $term_id, $_term, 'terms' );
181			}
182		}
183
184		$term_obj = new WP_Term( $_term );
185		$term_obj->filter( $term_obj->filter );
186
187		return $term_obj;
188	}
189
190	/**
191	 * Constructor.
192	 *
193	 * @since 4.4.0
194	 *
195	 * @param WP_Term|object $term Term object.
196	 */
197	public function __construct( $term ) {
198		foreach ( get_object_vars( $term ) as $key => $value ) {
199			$this->$key = $value;
200		}
201	}
202
203	/**
204	 * Sanitizes term fields, according to the filter type provided.
205	 *
206	 * @since 4.4.0
207	 *
208	 * @param string $filter Filter context. Accepts 'edit', 'db', 'display', 'attribute', 'js', 'rss', or 'raw'.
209	 */
210	public function filter( $filter ) {
211		sanitize_term( $this, $this->taxonomy, $filter );
212	}
213
214	/**
215	 * Converts an object to array.
216	 *
217	 * @since 4.4.0
218	 *
219	 * @return array Object as array.
220	 */
221	public function to_array() {
222		return get_object_vars( $this );
223	}
224
225	/**
226	 * Getter.
227	 *
228	 * @since 4.4.0
229	 *
230	 * @param string $key Property to get.
231	 * @return mixed Property value.
232	 */
233	public function __get( $key ) {
234		switch ( $key ) {
235			case 'data':
236				$data    = new stdClass();
237				$columns = array( 'term_id', 'name', 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', 'parent', 'count' );
238				foreach ( $columns as $column ) {
239					$data->{$column} = isset( $this->{$column} ) ? $this->{$column} : null;
240				}
241
242				return sanitize_term( $data, $data->taxonomy, 'raw' );
243		}
244	}
245}
246