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