Taxonomy: Deprecate wp_insert_category() and update internal callers to use generic term APIs

src/wp-admin/includes/taxonomy.php

@@ -58,12 +58,13 @@ function wp_create_category( $category_name, $category_parent = 0 ) {
 		return (int) $id;
 	}
 
-	return wp_insert_category(
-		array(
-			'cat_name'        => $category_name,
-			'category_parent' => $category_parent,
-		)
-	);
+	$result = wp_insert_term( $category_name, 'category', array( 'parent' => $category_parent ) );
+
+	if ( is_wp_error( $result ) ) {
+		return 0;
+	}
+
+	return (int) $result['term_id'];
 }
 
 /**
@@ -119,6 +120,8 @@ function wp_create_categories( $categories, $post_id = 0 ) {
  *                      depending on param `$wp_error`.
  */
 function wp_insert_category( $catarr, $wp_error = false ) {
+	_deprecated_function( __FUNCTION__, '7.1.0', 'wp_insert_term() or wp_update_term()' );
+
 	$cat_defaults = array(
 		'cat_ID'               => 0,
 		'taxonomy'             => 'category',
@@ -175,7 +178,7 @@ function wp_insert_category( $catarr, $wp_error = false ) {
 }
 
 /**
- * Aliases wp_insert_category() with minimal args.
+ * Updates an existing category.
  *
  * If you want to update only some fields of an existing category, call this
  * function with only the new values set inside $catarr.
@@ -202,7 +205,28 @@ function wp_update_category( $catarr ) {
 	// Merge old and new fields with new fields overwriting old ones.
 	$catarr = array_merge( $category, $catarr );
 
-	return wp_insert_category( $catarr );
+	$parent = (int) $catarr['category_parent'];
+	if ( $parent < 0 ) {
+		$parent = 0;
+	}
+	if ( $parent > 0 && ( ! term_exists( $parent, 'category' ) || term_is_ancestor_of( $cat_id, $parent, 'category' ) ) ) {
+		$parent = 0;
+	}
+
+	$args = array(
+		'name'        => $catarr['cat_name'],
+		'slug'        => $catarr['category_nicename'],
+		'parent'      => $parent,
+		'description' => $catarr['category_description'],
+	);
+
+	$result = wp_update_term( $cat_id, 'category', $args );
+
+	if ( is_wp_error( $result ) ) {
+		return 0;
+	}
+
+	return (int) $result['term_id'];
 }
 
 //

src/wp-includes/class-wp-xmlrpc-server.php

@@ -3454,24 +3454,23 @@ public function wp_newCategory( $args ) {
 			$category['description'] = '';
 		}
 
-		$new_category = array(
-			'cat_name'             => $category['name'],
-			'category_nicename'    => $category['slug'],
-			'category_parent'      => $category['parent_id'],
-			'category_description' => $category['description'],
+		$args = array(
+			'slug'        => $category['slug'],
+			'parent'      => $category['parent_id'],
+			'description' => $category['description'],
 		);
 
-		$cat_id = wp_insert_category( $new_category, true );
+		$cat_id = wp_insert_term( $category['name'], 'category', $args );
 		if ( is_wp_error( $cat_id ) ) {
 			if ( 'term_exists' === $cat_id->get_error_code() ) {
 				return (int) $cat_id->get_error_data();
 			} else {
 				return new IXR_Error( 500, __( 'Sorry, the category could not be created.' ) );
 			}
-		} elseif ( ! $cat_id ) {
-			return new IXR_Error( 500, __( 'Sorry, the category could not be created.' ) );
 		}
 
+		$cat_id = (int) $cat_id['term_id'];
+
 		/**
 		 * Fires after a new category has been successfully created via XML-RPC.
 		 *

tests/phpunit/tests/taxonomy.php

@@ -489,6 +489,9 @@ public function test_in_category() {
 		$this->assertTrue( in_category( $term['term_id'], $post ) );
 	}
 
+	/**
+	 * @expectedDeprecated wp_insert_category
+	 */
 	public function test_insert_category_create() {
 		$cat = array(
 			'cat_ID'   => 0,
@@ -498,6 +501,9 @@ public function test_insert_category_create() {
 		$this->assertIsNumeric( wp_insert_category( $cat, true ) );
 	}
 
+	/**
+	 * @expectedDeprecated wp_insert_category
+	 */
 	public function test_insert_category_update() {
 		$cat = array(
 			'cat_ID'   => 1,
@@ -507,6 +513,9 @@ public function test_insert_category_update() {
 		$this->assertSame( 1, wp_insert_category( $cat ) );
 	}
 
+	/**
+	 * @expectedDeprecated wp_insert_category
+	 */
 	public function test_insert_category_force_error_handle() {
 		$cat = array(
 			'cat_ID'   => 0,
@@ -516,6 +525,9 @@ public function test_insert_category_force_error_handle() {
 		$this->assertInstanceOf( 'WP_Error', wp_insert_category( $cat, true ) );
 	}
 
+	/**
+	 * @expectedDeprecated wp_insert_category
+	 */
 	public function test_insert_category_force_error_no_handle() {
 		$cat = array(
 			'cat_ID'   => 0,
@@ -525,6 +537,50 @@ public function test_insert_category_force_error_no_handle() {
 		$this->assertSame( 0, wp_insert_category( $cat, false ) );
 	}
 
+	/**
+	 * @ticket 18448
+	 */
+	public function test_wp_update_category() {
+		$cat_id = self::factory()->category->create( array( 'name' => 'Original Name' ) );
+
+		// Update name.
+		$result = wp_update_category(
+			array(
+				'cat_ID'   => $cat_id,
+				'cat_name' => 'Updated Name',
+			)
+		);
+		$this->assertSame( $cat_id, $result );
+		$this->assertSame( 'Updated Name', get_term( $cat_id, 'category' )->name );
+
+		// Self-parent returns false.
+		$this->assertFalse(
+			wp_update_category(
+				array(
+					'cat_ID'          => $cat_id,
+					'cat_name'        => 'Updated Name',
+					'category_parent' => $cat_id,
+				)
+			)
+		);
+
+		// Circular parent is reset to 0.
+		$child_id = self::factory()->category->create(
+			array(
+				'name'   => 'Child',
+				'parent' => $cat_id,
+			)
+		);
+		wp_update_category(
+			array(
+				'cat_ID'          => $cat_id,
+				'cat_name'        => 'Updated Name',
+				'category_parent' => $child_id,
+			)
+		);
+		$this->assertSame( 0, (int) get_term( $cat_id, 'category' )->parent );
+	}
+
 	public function test_get_ancestors_taxonomy_non_hierarchical() {
 		register_taxonomy( 'wptests_tax', 'post' );
 		$t = self::factory()->term->create(

tests/phpunit/tests/term.php

@@ -147,6 +147,9 @@ public function test_term_is_ancestor_of() {
 		wp_delete_term( $t2['term_id'], 'category' );
 	}
 
+	/**
+	 * @expectedDeprecated wp_insert_category
+	 */
 	public function test_wp_insert_delete_category() {
 		$term = rand_str();
 		$this->assertNull( category_exists( $term ) );