wp_insert_term() WordPress Function

The wp_insert_term() function is used to insert a new term into the database. The function takes two arguments: the term to insert and the taxonomy in which to insert the term. The function returns the ID of the newly inserted term.

wp_insert_term( string $term, string $taxonomy, array|string $args = array() ) #

Adds a new term to the database.

Description
Parameters
Return
Source
Related
- Uses
- Used By
Changelog

Description

A non-existent term is inserted in the following sequence:

The term is added to the term table, then related to the taxonomy.
If everything is correct, several actions are fired.
The ‘term_id_filter’ is evaluated.
The term cache is cleaned.
Several more actions are fired.
An array is returned containing the term_id and term_taxonomy_id.

If the ‘slug’ argument is not empty, then it is checked to see if the term is invalid. If it is not a valid, existing term, it is added and the term_id is given.

If the taxonomy is hierarchical, and the ‘parent’ argument is not empty, the term is inserted and the term_id will be given.

Error handling: If $taxonomy does not exist or $term is empty, a WP_Error object will be returned.

If the term already exists on the same hierarchical level, or the term slug and name are not unique, a WP_Error object will be returned.

Top ↑

Parameters

$term

(string)(Required)The term name to add.

$taxonomy

(string)(Required)The taxonomy to which to add the term.

$args

(array|string)(Optional)Array or query string of arguments for inserting a term.

'alias_of'
(string) Slug of the term to make this term an alias of. Default empty string. Accepts a term slug.
'description'
(string) The term description. Default empty string.
'parent'
(int) The id of the parent term. Default 0.
'slug'
(string) The term slug to use. Default empty string.

Default value: array()

Top ↑

Return

(array|WP_Error) An array of the new term data, WP_Error otherwise.

'term_id'
(int) The new term ID.
'term_taxonomy_id'
(int|string) The new term taxonomy ID. Can be a numeric string.

Top ↑

Source

File: wp-includes/taxonomy.php

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
     *
     * @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.
     */
    $term = apply_filters( 'pre_insert_term', $term, $taxonomy );
 
    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'];
 
    $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;
 
            wp_update_term(
                $alias->term_id,
                $taxonomy,
                array(
                    'term_group' => $term_group,
                )
            );
        }
    }
 
    /*
     * Prevent the creation of terms with duplicate names at the same level of a taxonomy hierarchy,
     * unless a unique slug has been explicitly provided.
     */
    $name_matches = get_terms(
        array(
            'taxonomy'               => $taxonomy,
            'name'                   => $name,
            'hide_empty'             => false,
            'parent'                 => $args['parent'],
            'update_term_meta_cache' => false,
        )
    );
 
    /*
     * The `name` match in `get_terms()` doesn't differentiate accented characters,
     * so we do a stricter comparison here.
     */
    $name_match = null;
    if ( $name_matches ) {
        foreach ( $name_matches as $_match ) {
            if ( strtolower( $name ) === strtolower( $_match->name ) ) {
                $name_match = $_match;
                break;
            }
        }
    }
 
    if ( $name_match ) {
        $slug_match = get_term_by( 'slug', $slug, $taxonomy );
        if ( ! $slug_provided || $name_match->slug === $slug || $slug_match ) {
            if ( is_taxonomy_hierarchical( $taxonomy ) ) {
                $siblings = get_terms(
                    array(
                        'taxonomy'               => $taxonomy,
                        'get'                    => 'all',
                        'parent'                 => $parent,
                        'update_term_meta_cache' => false,
                    )
                );
 
                $existing_term = null;
                $sibling_names = wp_list_pluck( $siblings, 'name' );
                $sibling_slugs = wp_list_pluck( $siblings, 'slug' );
 
                if ( ( ! $slug_provided || $name_match->slug === $slug ) && in_array( $name, $sibling_names, true ) ) {
                    $existing_term = $name_match;
                } elseif ( $slug_match && in_array( $slug, $sibling_slugs, true ) ) {
                    $existing_term = $slug_match;
                }
 
                if ( $existing_term ) {
                    return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id );
                }
            } else {
                return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id );
            }
        }
    }
 
    $slug = wp_unique_term_slug( $slug, (object) $args );
 
    $data = compact( 'name', 'slug', 'term_group' );
 
    /**
     * Filters term data before it is inserted into the database.
     *
     * @since 4.7.0
     *
     * @param array  $data     Term data to be inserted.
     * @param string $taxonomy Taxonomy slug.
     * @param array  $args     Arguments passed to wp_insert_term().
     */
    $data = apply_filters( 'wp_insert_term_data', $data, $taxonomy, $args );
 
    if ( false === $wpdb->insert( $wpdb->terms, $data ) ) {
        return new WP_Error( 'db_insert_error', __( 'Could not insert term into the database.' ), $wpdb->last_error );
    }
 
    $term_id = (int) $wpdb->insert_id;
 
    // Seems unreachable. However, is used in the case that a term name is provided, which sanitizes to an empty string.
    if ( empty( $slug ) ) {
        $slug = sanitize_title( $slug, $term_id );
 
        /** This action is documented in wp-includes/taxonomy.php */
        do_action( 'edit_terms', $term_id, $taxonomy );
        $wpdb->update( $wpdb->terms, compact( 'slug' ), compact( 'term_id' ) );
 
        /** This action is documented in wp-includes/taxonomy.php */
        do_action( 'edited_terms', $term_id, $taxonomy );
    }
 
    $tt_id = $wpdb->get_var( $wpdb->prepare( "SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy AS tt INNER JOIN $wpdb->terms AS t ON tt.term_id = t.term_id WHERE tt.taxonomy = %s AND t.term_id = %d", $taxonomy, $term_id ) );
 
    if ( ! empty( $tt_id ) ) {
        return array(
            'term_id'          => $term_id,
            'term_taxonomy_id' => $tt_id,
        );
    }
 
    if ( false === $wpdb->insert( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ) + array( 'count' => 0 ) ) ) {
        return new WP_Error( 'db_insert_error', __( 'Could not insert term taxonomy into the database.' ), $wpdb->last_error );
    }
 
    $tt_id = (int) $wpdb->insert_id;
 
    /*
     * Sanity check: if we just created a term with the same parent + taxonomy + slug but a higher term_id than
     * an existing term, then we have unwittingly created a duplicate term. Delete the dupe, and use the term_id
     * and term_taxonomy_id of the older term instead. Then return out of the function so that the "create" hooks
     * are not fired.
     */
    $duplicate_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.term_id, t.slug, tt.term_taxonomy_id, tt.taxonomy FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON ( tt.term_id = t.term_id ) WHERE t.slug = %s AND tt.parent = %d AND tt.taxonomy = %s AND t.term_id < %d AND tt.term_taxonomy_id != %d", $slug, $parent, $taxonomy, $term_id, $tt_id ) );
 
    /**
     * Filters the duplicate term check that takes place during term creation.
     *
     * Term parent + taxonomy + slug combinations are meant to be unique, and wp_insert_term()
     * performs a last-minute confirmation of this uniqueness before allowing a new term
     * to be created. Plugins with different uniqueness requirements may use this filter
     * to bypass or modify the duplicate-term check.
     *
     * @since 5.1.0
     *
     * @param object $duplicate_term Duplicate term row from terms table, if found.
     * @param string $term           Term being inserted.
     * @param string $taxonomy       Taxonomy name.
     * @param array  $args           Term arguments passed to the function.
     * @param int    $tt_id          term_taxonomy_id for the newly created term.
     */
    $duplicate_term = apply_filters( 'wp_insert_term_duplicate_term_check', $duplicate_term, $term, $taxonomy, $args, $tt_id );
 
    if ( $duplicate_term ) {
        $wpdb->delete( $wpdb->terms, array( 'term_id' => $term_id ) );
        $wpdb->delete( $wpdb->term_taxonomy, array( 'term_taxonomy_id' => $tt_id ) );
 
        $term_id = (int) $duplicate_term->term_id;
        $tt_id   = (int) $duplicate_term->term_taxonomy_id;
 
        clean_term_cache( $term_id, $taxonomy );
        return array(
            'term_id'          => $term_id,
            'term_taxonomy_id' => $tt_id,
        );
    }
 
    /**
     * Fires immediately after a new term is created, before the term cache is cleaned.
     *
     * The {@see 'create_$taxonomy'} hook is also available for targeting a specific
     * taxonomy.
     *
     * @since 2.3.0
     *
     * @param int    $term_id  Term ID.
     * @param int    $tt_id    Term taxonomy ID.
     * @param string $taxonomy Taxonomy slug.
     */
    do_action( 'create_term', $term_id, $tt_id, $taxonomy );
 
    /**
     * Fires after a new term is created for a specific taxonomy.
     *
     * The dynamic portion of the hook name, `$taxonomy`, refers
     * to the slug of the taxonomy the term was created for.
     *
     * Possible hook names include:
     *
     *  - `create_category`
     *  - `create_post_tag`
     *
     * @since 2.3.0
     *
     * @param int $term_id Term ID.
     * @param int $tt_id   Term taxonomy ID.
     */
    do_action( "create_{$taxonomy}", $term_id, $tt_id );
 
    /**
     * Filters the term ID after a new term is created.
     *
     * @since 2.3.0
     *
     * @param int $term_id Term ID.
     * @param int $tt_id   Term taxonomy ID.
     */
    $term_id = apply_filters( 'term_id_filter', $term_id, $tt_id );
 
    clean_term_cache( $term_id, $taxonomy );
 
    /**
     * Fires after a new term is created, and after the term cache has been cleaned.
     *
     * The {@see 'created_$taxonomy'} hook is also available for targeting a specific
     * taxonomy.
     *
     * @since 2.3.0
     *
     * @param int    $term_id  Term ID.
     * @param int    $tt_id    Term taxonomy ID.
     * @param string $taxonomy Taxonomy slug.
     */
    do_action( 'created_term', $term_id, $tt_id, $taxonomy );
 
    /**
     * Fires after a new term in a specific taxonomy is created, and after the term
     * cache has been cleaned.
     *
     * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
     *
     * Possible hook names include:
     *
     *  - `created_category`
     *  - `created_post_tag`
     *
     * @since 2.3.0
     *
     * @param int $term_id Term ID.
     * @param int $tt_id   Term taxonomy ID.
     */
    do_action( "created_{$taxonomy}", $term_id, $tt_id );
 
    /**
     * Fires after a term has been saved, and the term cache has been cleared.
     *
     * The {@see 'saved_$taxonomy'} hook is also available for targeting a specific
     * taxonomy.
     *
     * @since 5.5.0
     *
     * @param int    $term_id  Term ID.
     * @param int    $tt_id    Term taxonomy ID.
     * @param string $taxonomy Taxonomy slug.
     * @param bool   $update   Whether this is an existing term being updated.
     */
    do_action( 'saved_term', $term_id, $tt_id, $taxonomy, false );
 
    /**
     * Fires after a term in a specific taxonomy has been saved, and the term
     * cache has been cleared.
     *
     * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
     *
     * Possible hook names include:
     *
     *  - `saved_category`
     *  - `saved_post_tag`
     *
     * @since 5.5.0
     *
     * @param int  $term_id Term ID.
     * @param int  $tt_id   Term taxonomy ID.
     * @param bool $update  Whether this is an existing term being updated.
     */
    do_action( "saved_{$taxonomy}", $term_id, $tt_id, false );
 
    return array(
        'term_id'          => $term_id,
        'term_taxonomy_id' => $tt_id,
    );
}

Expand full source code Collapse full source codeView on TracView on GitHub

Top ↑

Uses

Uses
Uses	Description
wp-includes/taxonomy.php:saved_term	Fires after a term has been saved, and the term cache has been cleared.
wp-includes/taxonomy.php:saved_{$taxonomy}	Fires after a term in a specific taxonomy has been saved, and the term cache has been cleared.
wp-includes/taxonomy.php:wp_insert_term_duplicate_term_check	Filters the duplicate term check that takes place during term creation.
wp-includes/taxonomy.php:wp_insert_term_data	Filters term data before it is inserted into the database.
wp-includes/taxonomy.php:edit_terms	Fires immediately before the given terms are edited.
wp-includes/taxonomy.php:edited_terms	Fires immediately after a term is updated in the database, but before its term-taxonomy relationship is updated.
wp-includes/l10n.php:__()	Retrieve the translation of $text.
wp-includes/formatting.php:wp_unslash()	Removes slashes from a string or recursively removes slashes from strings within an array.
wp-includes/formatting.php:sanitize_title()	Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
wp-includes/functions.php:wp_parse_args()	Merges user defined arguments into defaults array.
wp-includes/functions.php:wp_list_pluck()	Plucks a certain field out of each object or array in an array.
wp-includes/taxonomy.php:clean_term_cache()	Removes all of the term IDs from the cache.
wp-includes/taxonomy.php:wp_update_term()	Updates term based on arguments provided.
wp-includes/taxonomy.php:wp_unique_term_slug()	Makes term slug unique, if it isn’t already.
wp-includes/taxonomy.php:pre_insert_term	Filters a term before it is sanitized and inserted into the database.
wp-includes/taxonomy.php:create_term	Fires immediately after a new term is created, before the term cache is cleaned.
wp-includes/taxonomy.php:create_{$taxonomy}	Fires after a new term is created for a specific taxonomy.
wp-includes/taxonomy.php:term_id_filter	Filters the term ID after a new term is created.
wp-includes/taxonomy.php:created_term	Fires after a new term is created, and after the term cache has been cleaned.
wp-includes/taxonomy.php:created_{$taxonomy}	Fires after a new term in a specific taxonomy is created, and after the term cache has been cleaned.
wp-includes/taxonomy.php:term_exists()	Determines whether a taxonomy term exists.
wp-includes/taxonomy.php:sanitize_term()	Sanitizes all term fields.
wp-includes/taxonomy.php:get_term_by()	Gets all term data from database by term field and data.
wp-includes/taxonomy.php:get_terms()	Retrieves the terms in a given taxonomy or list of taxonomies.
wp-includes/taxonomy.php:taxonomy_exists()	Determines whether the taxonomy name exists.
wp-includes/taxonomy.php:is_taxonomy_hierarchical()	Determines whether the taxonomy object is hierarchical.
wp-includes/plugin.php:apply_filters()	Calls the callback functions that have been added to a filter hook.
wp-includes/plugin.php:do_action()	Calls the callback functions that have been added to an action hook.
wp-includes/wp-db.php:wpdb::get_var()	Retrieves one variable from the database.
wp-includes/wp-db.php:wpdb::insert()	Inserts a row into the table.
wp-includes/wp-db.php:wpdb::update()	Updates a row in the table.
wp-includes/wp-db.php:wpdb::get_row()	Retrieves one row from the database.
wp-includes/wp-db.php:wpdb::delete()	Deletes a row in the table.
wp-includes/wp-db.php:wpdb::prepare()	Prepares a SQL query for safe execution.
wp-includes/load.php:is_wp_error()	Checks whether the given variable is a WordPress Error.
wp-includes/class-wp-error.php:WP_Error::__construct()	Initializes the error.

Show 31 more uses Hide more uses

Top ↑

Used By

Used By
Used By	Description
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php:WP_REST_Terms_Controller::create_item()	Creates a single term in a taxonomy.
wp-admin/includes/taxonomy.php:wp_insert_category()	Updates an existing Category or creates a new Category.
wp-admin/includes/taxonomy.php:wp_create_term()	Add a new term to the database if it does not already exist.
wp-admin/includes/ajax-actions.php:_wp_ajax_add_hierarchical_term()	Ajax handler for adding a hierarchical term.
wp-admin/includes/ajax-actions.php:wp_ajax_add_link_category()	Ajax handler for adding a link category.
wp-admin/includes/ajax-actions.php:wp_ajax_add_tag()	Ajax handler to add a tag.
wp-includes/taxonomy.php:wp_set_object_terms()	Creates term and taxonomy relationships.
wp-includes/taxonomy.php:register_taxonomy()	Creates or modifies a taxonomy object.
wp-includes/nav-menu.php:wp_update_nav_menu_object()	Saves the properties of a menu or create a new menu with those properties.
wp-includes/class-wp-xmlrpc-server.php:wp_xmlrpc_server::wp_newTerm()	Create a new term.
wp-includes/class-wp-xmlrpc-server.php:wp_xmlrpc_server::_insert_post()	Helper method for wp_newPost() and wp_editPost(), containing shared logic.