[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WordPress Taxonomy Administration API.
   4   *
   5   * @package WordPress
   6   * @subpackage Administration
   7   */
   8  
   9  //
  10  // Category.
  11  //
  12  
  13  /**
  14   * Checks whether a category exists.
  15   *
  16   * @since 2.0.0
  17   *
  18   * @see term_exists()
  19   *
  20   * @param int|string $cat_name        Category name.
  21   * @param int        $category_parent Optional. ID of parent category.
  22   * @return string|null Returns the category ID as a numeric string if the pairing exists, null if not.
  23   */
  24  function category_exists( $cat_name, $category_parent = null ) {
  25      $id = term_exists( $cat_name, 'category', $category_parent );
  26      if ( is_array( $id ) ) {
  27          $id = $id['term_id'];
  28      }
  29      return $id;
  30  }
  31  
  32  /**
  33   * Gets category object for given ID and 'edit' filter context.
  34   *
  35   * @since 2.0.0
  36   *
  37   * @param int $id
  38   * @return object
  39   */
  40  function get_category_to_edit( $id ) {
  41      $category = get_term( $id, 'category', OBJECT, 'edit' );
  42      _make_cat_compat( $category );
  43      return $category;
  44  }
  45  
  46  /**
  47   * Adds a new category to the database if it does not already exist.
  48   *
  49   * @since 2.0.0
  50   *
  51   * @param int|string $cat_name        Category name.
  52   * @param int        $category_parent Optional. ID of parent category.
  53   * @return int|WP_Error
  54   */
  55  function wp_create_category( $cat_name, $category_parent = 0 ) {
  56      $id = category_exists( $cat_name, $category_parent );
  57      if ( $id ) {
  58          return $id;
  59      }
  60  
  61      return wp_insert_category(
  62          array(
  63              'cat_name'        => $cat_name,
  64              'category_parent' => $category_parent,
  65          )
  66      );
  67  }
  68  
  69  /**
  70   * Creates categories for the given post.
  71   *
  72   * @since 2.0.0
  73   *
  74   * @param string[] $categories Array of category names to create.
  75   * @param int      $post_id    Optional. The post ID. Default empty.
  76   * @return int[] Array of IDs of categories assigned to the given post.
  77   */
  78  function wp_create_categories( $categories, $post_id = '' ) {
  79      $cat_ids = array();
  80      foreach ( $categories as $category ) {
  81          $id = category_exists( $category );
  82          if ( $id ) {
  83              $cat_ids[] = $id;
  84          } else {
  85              $id = wp_create_category( $category );
  86              if ( $id ) {
  87                  $cat_ids[] = $id;
  88              }
  89          }
  90      }
  91  
  92      if ( $post_id ) {
  93          wp_set_post_categories( $post_id, $cat_ids );
  94      }
  95  
  96      return $cat_ids;
  97  }
  98  
  99  /**
 100   * Updates an existing Category or creates a new Category.
 101   *
 102   * @since 2.0.0
 103   * @since 2.5.0 $wp_error parameter was added.
 104   * @since 3.0.0 The 'taxonomy' argument was added.
 105   *
 106   * @param array $catarr {
 107   *     Array of arguments for inserting a new category.
 108   *
 109   *     @type int        $cat_ID               Category ID. A non-zero value updates an existing category.
 110   *                                            Default 0.
 111   *     @type string     $taxonomy             Taxonomy slug. Default 'category'.
 112   *     @type string     $cat_name             Category name. Default empty.
 113   *     @type string     $category_description Category description. Default empty.
 114   *     @type string     $category_nicename    Category nice (display) name. Default empty.
 115   *     @type int|string $category_parent      Category parent ID. Default empty.
 116   * }
 117   * @param bool  $wp_error Optional. Default false.
 118   * @return int|WP_Error The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
 119   *                      depending on param `$wp_error`.
 120   */
 121  function wp_insert_category( $catarr, $wp_error = false ) {
 122      $cat_defaults = array(
 123          'cat_ID'               => 0,
 124          'taxonomy'             => 'category',
 125          'cat_name'             => '',
 126          'category_description' => '',
 127          'category_nicename'    => '',
 128          'category_parent'      => '',
 129      );
 130      $catarr       = wp_parse_args( $catarr, $cat_defaults );
 131  
 132      if ( '' === trim( $catarr['cat_name'] ) ) {
 133          if ( ! $wp_error ) {
 134              return 0;
 135          } else {
 136              return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
 137          }
 138      }
 139  
 140      $catarr['cat_ID'] = (int) $catarr['cat_ID'];
 141  
 142      // Are we updating or creating?
 143      $update = ! empty( $catarr['cat_ID'] );
 144  
 145      $name        = $catarr['cat_name'];
 146      $description = $catarr['category_description'];
 147      $slug        = $catarr['category_nicename'];
 148      $parent      = (int) $catarr['category_parent'];
 149      if ( $parent < 0 ) {
 150          $parent = 0;
 151      }
 152  
 153      if ( empty( $parent )
 154          || ! term_exists( $parent, $catarr['taxonomy'] )
 155          || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
 156          $parent = 0;
 157      }
 158  
 159      $args = compact( 'name', 'slug', 'parent', 'description' );
 160  
 161      if ( $update ) {
 162          $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
 163      } else {
 164          $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
 165      }
 166  
 167      if ( is_wp_error( $catarr['cat_ID'] ) ) {
 168          if ( $wp_error ) {
 169              return $catarr['cat_ID'];
 170          } else {
 171              return 0;
 172          }
 173      }
 174      return $catarr['cat_ID']['term_id'];
 175  }
 176  
 177  /**
 178   * Aliases wp_insert_category() with minimal args.
 179   *
 180   * If you want to update only some fields of an existing category, call this
 181   * function with only the new values set inside $catarr.
 182   *
 183   * @since 2.0.0
 184   *
 185   * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
 186   * @return int|false The ID number of the new or updated Category on success. Zero or FALSE on failure.
 187   */
 188  function wp_update_category( $catarr ) {
 189      $cat_id = (int) $catarr['cat_ID'];
 190  
 191      if ( isset( $catarr['category_parent'] ) && ( $cat_id === (int) $catarr['category_parent'] ) ) {
 192          return false;
 193      }
 194  
 195      // First, get all of the original fields.
 196      $category = get_term( $cat_id, 'category', ARRAY_A );
 197      _make_cat_compat( $category );
 198  
 199      // Escape data pulled from DB.
 200      $category = wp_slash( $category );
 201  
 202      // Merge old and new fields with new fields overwriting old ones.
 203      $catarr = array_merge( $category, $catarr );
 204  
 205      return wp_insert_category( $catarr );
 206  }
 207  
 208  //
 209  // Tags.
 210  //
 211  
 212  /**
 213   * Checks whether a post tag with a given name exists.
 214   *
 215   * @since 2.3.0
 216   *
 217   * @param int|string $tag_name
 218   * @return mixed Returns null if the term does not exist.
 219   *               Returns an array of the term ID and the term taxonomy ID if the pairing exists.
 220   *               Returns 0 if term ID 0 is passed to the function.
 221   */
 222  function tag_exists( $tag_name ) {
 223      return term_exists( $tag_name, 'post_tag' );
 224  }
 225  
 226  /**
 227   * Adds a new tag to the database if it does not already exist.
 228   *
 229   * @since 2.3.0
 230   *
 231   * @param int|string $tag_name
 232   * @return array|WP_Error
 233   */
 234  function wp_create_tag( $tag_name ) {
 235      return wp_create_term( $tag_name, 'post_tag' );
 236  }
 237  
 238  /**
 239   * Gets comma-separated list of tags available to edit.
 240   *
 241   * @since 2.3.0
 242   *
 243   * @param int    $post_id
 244   * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
 245   * @return string|false|WP_Error
 246   */
 247  function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 248      return get_terms_to_edit( $post_id, $taxonomy );
 249  }
 250  
 251  /**
 252   * Gets comma-separated list of terms available to edit for the given post ID.
 253   *
 254   * @since 2.8.0
 255   *
 256   * @param int    $post_id
 257   * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
 258   * @return string|false|WP_Error
 259   */
 260  function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 261      $post_id = (int) $post_id;
 262      if ( ! $post_id ) {
 263          return false;
 264      }
 265  
 266      $terms = get_object_term_cache( $post_id, $taxonomy );
 267      if ( false === $terms ) {
 268          $terms = wp_get_object_terms( $post_id, $taxonomy );
 269          wp_cache_add( $post_id, wp_list_pluck( $terms, 'term_id' ), $taxonomy . '_relationships' );
 270      }
 271  
 272      if ( ! $terms ) {
 273          return false;
 274      }
 275      if ( is_wp_error( $terms ) ) {
 276          return $terms;
 277      }
 278      $term_names = array();
 279      foreach ( $terms as $term ) {
 280          $term_names[] = $term->name;
 281      }
 282  
 283      $terms_to_edit = esc_attr( implode( ',', $term_names ) );
 284  
 285      /**
 286       * Filters the comma-separated list of terms available to edit.
 287       *
 288       * @since 2.8.0
 289       *
 290       * @see get_terms_to_edit()
 291       *
 292       * @param string $terms_to_edit A comma-separated list of term names.
 293       * @param string $taxonomy      The taxonomy name for which to retrieve terms.
 294       */
 295      $terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
 296  
 297      return $terms_to_edit;
 298  }
 299  
 300  /**
 301   * Adds a new term to the database if it does not already exist.
 302   *
 303   * @since 2.8.0
 304   *
 305   * @param string $tag_name The term name.
 306   * @param string $taxonomy Optional. The taxonomy within which to create the term. Default 'post_tag'.
 307   * @return array|WP_Error
 308   */
 309  function wp_create_term( $tag_name, $taxonomy = 'post_tag' ) {
 310      $id = term_exists( $tag_name, $taxonomy );
 311      if ( $id ) {
 312          return $id;
 313      }
 314  
 315      return wp_insert_term( $tag_name, $taxonomy );
 316  }