wp-includes/taxonomy.php:2418Adds a new term to the database.
$termstring$taxonomystring$argsarray|stringoptionalarray()$alias_ofstringdefault: empty string. Accepts a term slug
$descriptionstringdefault: empty string
$parentintdefault: 0
$slugstringdefault: empty string
array|WP_Error$term_idint
$term_taxonomy_idint|string
12 hooks fire while wp_insert_term() runs, in this order:
Filters a term before it is sanitized and inserted into the database.
Filters term data before it is inserted into the database.
Fires immediately before the given terms are edited.
Fires immediately after a term is updated in the database, but before its term-taxonomy relationship is updated.
Filters the duplicate term check that takes place during term creation.
Fires immediately after a new term is created, before the term cache is cleaned.
Fires after a new term is created for a specific taxonomy.
Filters the term ID after a new term is created.
Fires after a new term is created, and after the term cache has been cleaned.
Fires after a new term in a specific taxonomy is created, and after the term cache has been cleaned.
Fires after a term has been saved, and the term cache has been cleared.
Fires after a term in a specific taxonomy has been saved, and the term cache has been cleared.
function wp_insert_term( $term, $taxonomy, $args = array() ) { global $wpdb; if ( ! taxonomy_exists( $taxonomy ) ) { return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); } /** * Filters a term before it is sanitized and inserted into the database. * * @since 3.0.0 * @since 6.1.0 The `$args` parameter was added. * * @param string|WP_Error $term The term name to add, or a WP_Error object if there's an error. * @param string $taxonomy Taxonomy slug. * @param array|string $args Array or query string of arguments passed to wp_insert_term(). */ $term = apply_filters( 'pre_insert_term', $term, $taxonomy, $args ); if ( is_wp_error( $term ) ) { return $term; } if ( is_int( $term ) && 0 === $term ) { return new WP_Error( 'invalid_term_id', __( 'Invalid term ID.' ) ); } if ( '' === trim( $term ) ) { return new WP_Error( 'empty_term_name', __( 'A name is required for this term.' ) ); } $defaults = array( 'alias_of' => '', 'description' => '', 'parent' => 0, 'slug' => '', ); $args = wp_parse_args( $args, $defaults ); if ( (int) $args['parent'] > 0 && ! term_exists( (int) $args['parent'] ) ) { return new WP_Error( 'missing_parent', __( 'Parent term does not exist.' ) ); } $args['name'] = $term; $args['taxonomy'] = $taxonomy; // Coerce null description to strings, to avoid database errors. $args['description'] = (string) $args['description']; $args = sanitize_term( $args, $taxonomy, 'db' ); // expected_slashed ($name) $name = wp_unslash( $args['name'] ); $description = wp_unslash( $args['description'] ); $parent = (int) $args['parent']; // Sanitization could clean the name to an empty string that must be checked again. if ( '' === $name ) { return new WP_Error( 'invalid_term_name', __( 'Invalid term name.' ) ); } $slug_provided = ! empty( $args['slug'] ); if ( ! $slug_provided ) { $slug = sanitize_title( $name ); } else { $slug = $args['slug']; } $term_group = 0; if ( $args['alias_of'] ) { $alias = get_term_by( 'slug', $args['alias_of'], $taxonomy ); if ( ! empty( $alias->term_group ) ) { // The alias we want is already in a group, so let's use that one. $term_group = $alias->term_group; } elseif ( ! empty( $alias->term_id ) ) { /* * The alias is not in a group, so we create a new one * and add the alias to it. */ $term_group = $wpdb->get_var( "SELECT MAX(term_group) FROM $wpdb->terms" ) + 1;Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
src/wp-includes/taxonomy.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.