Introduce WP_Term.

`get_term()` now returns a `WP_Term` object, instead of a `stdClass` object.
Cache support and sanitization filters for individual terms are now more
centralized. For example, `get_term_by()` is able to cast results of its query
to a `WP_Term` object by passing it through `get_term()`.

The `$taxonomy` parameter for `get_term()` is now optional, as terms ought to
be unique to a taxonomy (ie, shared terms no longer exist). In cases where
`get_term()` detects that the term matching the specified term_id is from the
wrong taxonomy, it checks to see if you've requested a shared term, and if so,
it splits the term. This is used only for fallback purposes.

The elimination of shared terms allows the caching strategy for terms to be
simplified. Individual terms are now cached in a single 'terms' bucket.

Props flixos90, boonebgorges, scribu, dipesh.kakadiya.
See #14162.

git-svn-id: https://develop.svn.wordpress.org/trunk@34997 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/class-wp-term.php

@@ -0,0 +1,187 @@
+<?php
+/**
+ * Taxonomy API: WP_Term class
+ *
+ * @package WordPress
+ * @subpackage Taxonomy
+ * @since 4.4.0
+ */
+
+/**
+ * Core class used to implement the WP_Term object.
+ *
+ * @since 4.4.0
+ */
+final class WP_Term {
+
+	/**
+	 * Term ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var int
+	 */
+	public $term_id;
+
+	/**
+	 * The term's name.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $name = '';
+
+	/**
+	 * The term's slug.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $slug = '';
+
+	/**
+	 * The term's term_group.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $term_group = '';
+
+	/**
+	 * Term Taxonomy ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var int
+	 */
+	public $term_taxonomy_id = 0;
+
+	/**
+	 * The term's taxonomy name.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $taxonomy = '';
+
+	/**
+	 * The term's description.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $description = '';
+
+	/**
+	 * ID of a term's parent term.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var int
+	 */
+	public $parent = 0;
+
+	/**
+	 * Cached object count for this term.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var int
+	 */
+	public $count = 0;
+
+	/**
+	 * Stores the term object's sanitization level.
+	 *
+	 * Does not correspond to a database field.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
+	 */
+	public $filter = 'raw';
+
+	/**
+	 * Retrieve WP_Term instance.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @static
+	 *
+	 * @global wpdb $wpdb WordPress database abstraction object.
+	 *
+	 * @param int $term_id Term ID.
+	 * @return WP_Term|false Term object, false otherwise.
+	 */
+	public static function get_instance( $term_id ) {
+		global $wpdb;
+
+		$term_id = (int) $term_id;
+		if ( ! $term_id ) {
+			return false;
+		}
+
+		$_term = wp_cache_get( $term_id, 'terms' );
+
+		// If there isn't a cached version, hit the database.
+		if ( ! $_term ) {
+			$_term = $wpdb->get_row( $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 LIMIT 1", $term_id ) );
+			if ( ! $_term ) {
+				return false;
+			}
+
+			$_term = sanitize_term( $_term, $_term->taxonomy, 'raw' );
+			wp_cache_add( $term_id, $_term, 'terms' );
+		}
+
+		return new WP_Term( $_term );
+	}
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @param WP_Term|object $term Term object.
+	 */
+	public function __construct( $term ) {
+		foreach ( get_object_vars( $term ) as $key => $value ) {
+			$this->$key = $value;
+		}
+	}
+
+	/**
+	 * Sanitizes term fields, according to the filter type provided.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @param string $filter Filter context. Accepts 'edit', 'db', 'display', 'attribute', 'js', 'raw'.
+	 */
+	public function filter( $filter ) {
+		// Term has already been filtered - nothing more to do.
+		if ( isset( $this->filter ) && $this->filter === $filter ) {
+			return;
+		}
+
+		sanitize_term( $this, $this->taxonomy, $filter );
+	}
+
+	/**
+	 * Converts an object to array.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @return array Object as array.
+	 */
+	public function to_array() {
+		return get_object_vars( $this );
+	}
+}