[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 string $category_name   Category name.
  52   * @param int    $category_parent Optional. ID of parent category.
  53   * @return int The ID of category term on success, or zero on failure.
  54   */
  55  function wp_create_category( $category_name, $category_parent = 0 ) {
  56      $id = category_exists( $category_name, $category_parent );
  57      if ( $id ) {
  58          return (int) $id;
  59      }
  60  
  61      return wp_insert_category(
  62          array(
  63              'cat_name'        => $category_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 = 0 ) {
  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   * @phpstan-return (
 122   *     $wp_error is false ? int : int|WP_Error
 123   * )
 124   */
 125  function wp_insert_category( $catarr, $wp_error = false ) {
 126      $cat_defaults = array(
 127          'cat_ID'               => 0,
 128          'taxonomy'             => 'category',
 129          'cat_name'             => '',
 130          'category_description' => '',
 131          'category_nicename'    => '',
 132          'category_parent'      => '',
 133      );
 134      $catarr       = wp_parse_args( $catarr, $cat_defaults );
 135  
 136      if ( '' === trim( $catarr['cat_name'] ) ) {
 137          if ( ! $wp_error ) {
 138              return 0;
 139          } else {
 140              return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
 141          }
 142      }
 143  
 144      $catarr['cat_ID'] = (int) $catarr['cat_ID'];
 145  
 146      // Are we updating or creating?
 147      $update = ! empty( $catarr['cat_ID'] );
 148  
 149      $name        = $catarr['cat_name'];
 150      $description = $catarr['category_description'];
 151      $slug        = $catarr['category_nicename'];
 152      $parent      = (int) $catarr['category_parent'];
 153      if ( $parent < 0 ) {
 154          $parent = 0;
 155      }
 156  
 157      if ( empty( $parent )
 158          || ! term_exists( $parent, $catarr['taxonomy'] )
 159          || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
 160          $parent = 0;
 161      }
 162  
 163      $args = compact( 'name', 'slug', 'parent', 'description' );
 164  
 165      if ( $update ) {
 166          $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
 167      } else {
 168          $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
 169      }
 170  
 171      if ( is_wp_error( $catarr['cat_ID'] ) ) {
 172          if ( $wp_error ) {
 173              return $catarr['cat_ID'];
 174          } else {
 175              return 0;
 176          }
 177      }
 178      return $catarr['cat_ID']['term_id'];
 179  }
 180  
 181  /**
 182   * Aliases wp_insert_category() with minimal args.
 183   *
 184   * If you want to update only some fields of an existing category, call this
 185   * function with only the new values set inside $catarr.
 186   *
 187   * @since 2.0.0
 188   *
 189   * @param array $catarr The 'cat_ID' value is required. All other keys are optional.
 190   * @return int|false The ID number of the new or updated Category on success. Zero or FALSE on failure.
 191   */
 192  function wp_update_category( $catarr ) {
 193      $cat_id = (int) $catarr['cat_ID'];
 194  
 195      if ( isset( $catarr['category_parent'] ) && ( $cat_id === (int) $catarr['category_parent'] ) ) {
 196          return false;
 197      }
 198  
 199      // First, get all of the original fields.
 200      $category = get_term( $cat_id, 'category', ARRAY_A );
 201      _make_cat_compat( $category );
 202  
 203      // Escape data pulled from DB.
 204      $category = wp_slash( $category );
 205  
 206      // Merge old and new fields with new fields overwriting old ones.
 207      $catarr = array_merge( $category, $catarr );
 208  
 209      return wp_insert_category( $catarr );
 210  }
 211  
 212  //
 213  // Tags.
 214  //
 215  
 216  /**
 217   * Checks whether a post tag with a given name exists.
 218   *
 219   * @since 2.3.0
 220   *
 221   * @param int|string $tag_name
 222   * @return mixed Returns null if the term does not exist.
 223   *               Returns an array of the term ID and the term taxonomy ID if the pairing exists.
 224   *               Returns 0 if term ID 0 is passed to the function.
 225   *
 226   * @phpstan-return (
 227   *     $tag_name is 0
 228   *         ? 0
 229   *         : ( $tag_name is '' ? null : array{ term_id: string, term_taxonomy_id: string }|null )
 230   * )
 231   */
 232  function tag_exists( $tag_name ) {
 233      return term_exists( $tag_name, 'post_tag' );
 234  }
 235  
 236  /**
 237   * Adds a new tag to the database if it does not already exist.
 238   *
 239   * @since 2.3.0
 240   *
 241   * @param int|string $tag_name
 242   * @return array|WP_Error
 243   */
 244  function wp_create_tag( $tag_name ) {
 245      return wp_create_term( $tag_name, 'post_tag' );
 246  }
 247  
 248  /**
 249   * Gets comma-separated list of tags available to edit.
 250   *
 251   * @since 2.3.0
 252   *
 253   * @param int    $post_id
 254   * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
 255   * @return string|false|WP_Error
 256   */
 257  function get_tags_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 258      return get_terms_to_edit( $post_id, $taxonomy );
 259  }
 260  
 261  /**
 262   * Gets comma-separated list of terms available to edit for the given post ID.
 263   *
 264   * @since 2.8.0
 265   *
 266   * @param int    $post_id
 267   * @param string $taxonomy Optional. The taxonomy for which to retrieve terms. Default 'post_tag'.
 268   * @return string|false|WP_Error
 269   */
 270  function get_terms_to_edit( $post_id, $taxonomy = 'post_tag' ) {
 271      $post_id = (int) $post_id;
 272      if ( ! $post_id ) {
 273          return false;
 274      }
 275  
 276      $terms = get_object_term_cache( $post_id, $taxonomy );
 277      if ( false === $terms ) {
 278          $terms = wp_get_object_terms( $post_id, $taxonomy );
 279          wp_cache_add( $post_id, wp_list_pluck( $terms, 'term_id' ), $taxonomy . '_relationships' );
 280      }
 281  
 282      if ( ! $terms ) {
 283          return false;
 284      }
 285      if ( is_wp_error( $terms ) ) {
 286          return $terms;
 287      }
 288      $term_names = array();
 289      foreach ( $terms as $term ) {
 290          $term_names[] = $term->name;
 291      }
 292  
 293      $terms_to_edit = esc_attr( implode( ',', $term_names ) );
 294  
 295      /**
 296       * Filters the comma-separated list of terms available to edit.
 297       *
 298       * @since 2.8.0
 299       *
 300       * @see get_terms_to_edit()
 301       *
 302       * @param string $terms_to_edit A comma-separated list of term names.
 303       * @param string $taxonomy      The taxonomy name for which to retrieve terms.
 304       */
 305      $terms_to_edit = apply_filters( 'terms_to_edit', $terms_to_edit, $taxonomy );
 306  
 307      return $terms_to_edit;
 308  }
 309  
 310  /**
 311   * Adds a new term to the database if it does not already exist.
 312   *
 313   * @since 2.8.0
 314   *
 315   * @param string $tag_name The term name.
 316   * @param string $taxonomy Optional. The taxonomy within which to create the term. Default 'post_tag'.
 317   * @return array|WP_Error
 318   */
 319  function wp_create_term( $tag_name, $taxonomy = 'post_tag' ) {
 320      $id = term_exists( $tag_name, $taxonomy );
 321      if ( $id ) {
 322          return $id;
 323      }
 324  
 325      return wp_insert_term( $tag_name, $taxonomy );
 326  }