You appear to be a bot. Output may be restricted

Description

Adds a new term to the database.

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

1. The term is added to the term table, then related to the taxonomy.
2. If everything is correct, several actions are fired.
3. The 'term_id_filter' is evaluated.
4. The term cache is cleaned.
5. Several more actions are fired.
6. 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.

Usage

$array|WP_Error = wp_insert_term( $term, $taxonomy, $args );

Parameters

$term

( string ) required – The term name to add.

$taxonomy

( string ) required – The taxonomy to which to add the term.

$args

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

$alias_of

( string ) optional – Slug of the term to make this term an alias of. Default empty string. Accepts a term slug.

$description

( string ) optional – The term description. Default empty string.

$parent

( int ) optional – The id of the parent term. Default 0.

$slug

( string ) optional – The term slug to use. Default empty string. }

$term_id

( int ) optional – The new term ID.

$term_taxonomy_id

( int|string ) optional – The new term taxonomy ID. Can be a numeric string. }

Returns

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

Source

File name: wordpress/wp-includes/taxonomy.php
Lines:

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'];

  $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,
    )
  );

 

 View on GitHub View on Trac