/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 * @property-read object $data Sanitized term data.
 16 */
 17final 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 string
 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	 * @static
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', '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}