/src/wp-content/plugins/advanced-custom-fields-pro/includes/api/api-term.php
PHP | 498 lines | 186 code | 87 blank | 225 comment | 30 complexity | 0f9b4fcda7f266b753e61525c14f1cab MD5 | raw file
Possible License(s): GPL-2.0, 0BSD
- <?php
- /*
- * acf_get_taxonomies
- *
- * Returns an array of taxonomy names.
- *
- * @date 7/10/13
- * @since 5.0.0
- *
- * @param array $args An array of args used in the get_taxonomies() function.
- * @return array An array of taxonomy names.
- */
- function acf_get_taxonomies( $args = array() ) {
- // vars
- $taxonomies = array();
-
- // get taxonomy objects
- $objects = get_taxonomies( $args, 'objects' );
-
- // loop
- foreach( $objects as $i => $object ) {
-
- // bail early if is builtin (WP) private post type
- // - nav_menu_item, revision, customize_changeset, etc
- if( $object->_builtin && !$object->public ) continue;
-
- // append
- $taxonomies[] = $i;
- }
-
- // custom post_type arg which does not yet exist in core
- if( isset($args['post_type']) ) {
- $taxonomies = acf_get_taxonomies_for_post_type($args['post_type']);
- }
-
- // filter
- $taxonomies = apply_filters('acf/get_taxonomies', $taxonomies, $args);
-
- // return
- return $taxonomies;
- }
- /**
- * acf_get_taxonomies_for_post_type
- *
- * Returns an array of taxonomies for a given post type(s)
- *
- * @date 7/9/18
- * @since 5.7.5
- *
- * @param string|array $post_types The post types to compare against.
- * @return array
- */
- function acf_get_taxonomies_for_post_type( $post_types = 'post' ) {
-
- // vars
- $taxonomies = array();
-
- // loop
- foreach( (array) $post_types as $post_type ) {
- $object_taxonomies = get_object_taxonomies( $post_type );
- foreach( (array) $object_taxonomies as $taxonomy ) {
- $taxonomies[] = $taxonomy;
- }
- }
-
- // remove duplicates
- $taxonomies = array_unique($taxonomies);
-
- // return
- return $taxonomies;
- }
- /*
- * acf_get_taxonomy_labels
- *
- * Returns an array of taxonomies in the format "name => label" for use in a select field.
- *
- * @date 3/8/18
- * @since 5.7.2
- *
- * @param array $taxonomies Optional. An array of specific taxonomies to return.
- * @return array
- */
- function acf_get_taxonomy_labels( $taxonomies = array() ) {
-
- // default
- if( empty($taxonomies) ) {
- $taxonomies = acf_get_taxonomies();
- }
-
- // vars
- $ref = array();
- $data = array();
-
- // loop
- foreach( $taxonomies as $taxonomy ) {
-
- // vars
- $object = get_taxonomy( $taxonomy );
- $label = $object->labels->singular_name;
-
- // append
- $data[ $taxonomy ] = $label;
-
- // increase counter
- if( !isset($ref[ $label ]) ) {
- $ref[ $label ] = 0;
- }
- $ref[ $label ]++;
- }
-
- // show taxonomy name next to label for shared labels
- foreach( $data as $taxonomy => $label ) {
- if( $ref[$label] > 1 ) {
- $data[ $taxonomy ] .= ' (' . $taxonomy . ')';
- }
- }
-
- // return
- return $data;
- }
- /**
- * acf_get_term_title
- *
- * Returns the title for this term object.
- *
- * @date 10/9/18
- * @since 5.0.0
- *
- * @param object $term The WP_Term object.
- * @return string
- */
- function acf_get_term_title( $term ) {
-
- // set to term name
- $title = $term->name;
-
- // allow for empty name
- if( $title === '' ) {
- $title = __('(no title)', 'acf');
- }
-
- // prepent ancestors indentation
- if( is_taxonomy_hierarchical($term->taxonomy) ) {
- $ancestors = get_ancestors( $term->term_id, $term->taxonomy );
- $title = str_repeat('- ', count($ancestors)) . $title;
- }
-
- // return
- return $title;
- }
- /**
- * acf_get_grouped_terms
- *
- * Returns an array of terms for the given query $args and groups by taxonomy name.
- *
- * @date 2/8/18
- * @since 5.7.2
- *
- * @param array $args An array of args used in the get_terms() function.
- * @return array
- */
- function acf_get_grouped_terms( $args ) {
-
- // vars
- $data = array();
-
- // defaults
- $args = wp_parse_args($args, array(
- 'taxonomy' => null,
- 'hide_empty' => false,
- 'update_term_meta_cache' => false,
- ));
-
- // vars
- $taxonomies = acf_get_taxonomy_labels( acf_get_array($args['taxonomy']) );
- $is_single = (count($taxonomies) == 1);
-
- // specify exact taxonomies required for _acf_terms_clauses() to work.
- $args['taxonomy'] = array_keys($taxonomies);
-
- // add filter to group results by taxonomy
- if( !$is_single ) {
- add_filter('terms_clauses', '_acf_terms_clauses', 10, 3);
- }
-
- // get terms
- $terms = get_terms( $args );
-
- // remove this filter (only once)
- if( !$is_single ) {
- remove_filter('terms_clauses', '_acf_terms_clauses', 10, 3);
- }
-
- // loop
- foreach( $taxonomies as $taxonomy => $label ) {
-
- // vars
- $this_terms = array();
-
- // populate $this_terms
- foreach( $terms as $term ) {
- if( $term->taxonomy == $taxonomy ) {
- $this_terms[] = $term;
- }
- }
-
- // bail early if no $items
- if( empty($this_terms) ) continue;
-
- // sort into hierachial order
- // this will fail if a search has taken place because parents wont exist
- if( is_taxonomy_hierarchical($taxonomy) && empty($args['s'])) {
-
- // get all terms from this taxonomy
- $all_terms = get_terms(array_merge($args, array(
- 'number' => 0,
- 'offset' => 0,
- 'taxonomy' => $taxonomy
- )));
-
- // vars
- $length = count($this_terms);
- $offset = 0;
-
- // find starting point (offset)
- foreach( $all_terms as $i => $term ) {
- if( $term->term_id == $this_terms[0]->term_id ) {
- $offset = $i;
- break;
- }
- }
-
- // order terms
- $parent = acf_maybe_get( $args, 'parent', 0 );
- $parent = acf_maybe_get( $args, 'child_of', $parent );
- $ordered_terms = _get_term_children( $parent, $all_terms, $taxonomy );
-
- // compare aray lengths
- // if $ordered_posts is smaller than $all_posts, WP has lost posts during the get_page_children() function
- // this is possible when get_post( $args ) filter out parents (via taxonomy, meta and other search parameters)
- if( count($ordered_terms) == count($all_terms) ) {
- $this_terms = array_slice($ordered_terms, $offset, $length);
- }
- }
-
- // populate group
- $data[ $label ] = array();
- foreach( $this_terms as $term ) {
- $data[ $label ][ $term->term_id ] = $term;
- }
- }
-
- // return
- return $data;
- }
- /**
- * _acf_terms_clauses
- *
- * Used in the 'terms_clauses' filter to order terms by taxonomy name.
- *
- * @date 2/8/18
- * @since 5.7.2
- *
- * @param array $pieces Terms query SQL clauses.
- * @param array $taxonomies An array of taxonomies.
- * @param array $args An array of terms query arguments.
- * @return array $pieces
- */
- function _acf_terms_clauses( $pieces, $taxonomies, $args ) {
-
- // prepend taxonomy to 'orderby' SQL
- if( is_array($taxonomies) ) {
- $sql = "FIELD(tt.taxonomy,'" . implode("', '", array_map('esc_sql', $taxonomies)) . "')";
- $pieces['orderby'] = str_replace("ORDER BY", "ORDER BY $sql,", $pieces['orderby']);
- }
-
- // return
- return $pieces;
- }
- /**
- * acf_get_pretty_taxonomies
- *
- * Deprecated in favor of acf_get_taxonomy_labels() function.
- *
- * @date 7/10/13
- * @since 5.0.0
- * @deprecated 5.7.2
- */
- function acf_get_pretty_taxonomies( $taxonomies = array() ) {
- return acf_get_taxonomy_labels( $taxonomies );
- }
- /**
- * acf_get_term
- *
- * Similar to get_term() but with some extra functionality.
- *
- * @date 19/8/18
- * @since 5.7.3
- *
- * @param mixed $term_id The term ID or a string of "taxonomy:slug".
- * @param string $taxonomy The taxonomyname.
- * @return WP_Term
- */
- function acf_get_term( $term_id, $taxonomy = '' ) {
-
- // allow $term_id parameter to be a string of "taxonomy:slug" or "taxonomy:id"
- if( is_string($term_id) && strpos($term_id, ':') ) {
- list( $taxonomy, $term_id ) = explode(':', $term_id);
- $term = get_term_by( 'slug', $term_id, $taxonomy );
- if( $term ) return $term;
- }
-
- // return
- return get_term( $term_id, $taxonomy );
- }
- /**
- * acf_encode_term
- *
- * Returns a "taxonomy:slug" string for a given WP_Term.
- *
- * @date 27/8/18
- * @since 5.7.4
- *
- * @param WP_Term $term The term object.
- * @return string
- */
- function acf_encode_term( $term ) {
- return "{$term->taxonomy}:{$term->slug}";
- }
- /**
- * acf_decode_term
- *
- * Decodes a "taxonomy:slug" string into an array of taxonomy and slug.
- *
- * @date 27/8/18
- * @since 5.7.4
- *
- * @param WP_Term $term The term object.
- * @return string
- */
- function acf_decode_term( $string ) {
- if( is_string($string) && strpos($string, ':') ) {
- list( $taxonomy, $slug ) = explode(':', $string);
- return compact( 'taxonomy', 'slug' );
- }
- return false;
- }
- /**
- * acf_get_encoded_terms
- *
- * Returns an array of WP_Term objects from an array of encoded strings
- *
- * @date 9/9/18
- * @since 5.7.5
- *
- * @param array $values The array of encoded strings.
- * @return array
- */
- function acf_get_encoded_terms( $values ) {
-
- // vars
- $terms = array();
-
- // loop over values
- foreach( (array) $values as $value ) {
-
- // find term from string
- $term = acf_get_term( $value );
-
- // append
- if( $term instanceof WP_Term ) {
- $terms[] = $term;
- }
- }
-
- // return
- return $terms;
- }
- /**
- * acf_get_choices_from_terms
- *
- * Returns an array of choices from the terms provided.
- *
- * @date 8/9/18
- * @since 5.7.5
- *
- * @param array $values and array of WP_Terms objects or encoded strings.
- * @param string $format The value format (term_id, slug).
- * @return array
- */
- function acf_get_choices_from_terms( $terms, $format = 'term_id' ) {
-
- // vars
- $groups = array();
-
- // get taxonomy lables
- $labels = acf_get_taxonomy_labels();
-
- // convert array of encoded strings to terms
- $term = reset($terms);
- if( !$term instanceof WP_Term ) {
- $terms = acf_get_encoded_terms( $terms );
- }
-
- // loop over terms
- foreach( $terms as $term ) {
- $group = $labels[ $term->taxonomy ];
- $choice = acf_get_choice_from_term( $term, $format );
- $groups[ $group ][ $choice['id'] ] = $choice['text'];
- }
-
- // return
- return $groups;
- }
- /**
- * acf_get_choices_from_grouped_terms
- *
- * Returns an array of choices from the grouped terms provided.
- *
- * @date 8/9/18
- * @since 5.7.5
- *
- * @param array $value A grouped array of WP_Terms objects.
- * @param string $format The value format (term_id, slug).
- * @return array
- */
- function acf_get_choices_from_grouped_terms( $value, $format = 'term_id' ) {
-
- // vars
- $groups = array();
-
- // loop over values
- foreach( $value as $group => $terms ) {
- $groups[ $group ] = array();
- foreach( $terms as $term_id => $term ) {
- $choice = acf_get_choice_from_term( $term, $format );
- $groups[ $group ][ $choice['id'] ] = $choice['text'];
- }
- }
-
- // return
- return $groups;
- }
- /**
- * acf_get_choice_from_term
- *
- * Returns an array containing the id and text for this item.
- *
- * @date 10/9/18
- * @since 5.7.6
- *
- * @param object $item The item object such as WP_Post or WP_Term.
- * @param string $format The value format (term_id, slug)
- * @return array
- */
- function acf_get_choice_from_term( $term, $format = 'term_id' ) {
-
- // vars
- $id = $term->term_id;
- $text = acf_get_term_title( $term );
-
- // return format
- if( $format == 'slug' ) {
- $id = acf_encode_term($term);
- }
-
- // return
- return array(
- 'id' => $id,
- 'text' => $text
- );
- }
- ?>