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