function taxonomy_term_save

taxonomy_term_save($term)

Saves a term object to the database.

Parameters

$term: The taxonomy term object with the following properties:

• vid: The ID of the vocabulary the term is assigned to.
• name: The name of the term.
• tid: (optional) The unique ID for the term being saved. If $term->tid is empty or omitted, a new term will be inserted.
• description: (optional) The term's description.
• format: (optional) The text format for the term's description.
• weight: (optional) The weight of this term in relation to other terms within the same vocabulary.
• parent: (optional) The parent term(s) for this term. This can be a single term ID or an array of term IDs. A value of 0 means this term does not have any parents. When omitting this variable during an update, the existing hierarchy for the term remains unchanged.
• vocabulary_machine_name: (optional) The machine name of the vocabulary the term is assigned to. If not given, this value will be set automatically by loading the vocabulary based on $term->vid.
• original: (optional) The original taxonomy term object before any changes were applied. When omitted, the unchanged taxonomy term object is loaded from the database and stored in this property.

Since a taxonomy term is an entity, any fields contained in the term object are saved alongside the term object.

Return value

Status constant indicating whether term was inserted (SAVED_NEW) or updated (SAVED_UPDATED). When inserting a new term, $term->tid will contain the term ID of the newly created term.

File

modules/taxonomy/taxonomy.module, line 626

Enables the organization of content into categories.

Code

function taxonomy_term_save($term) {
  // Prevent leading and trailing spaces in term names.
  $term->name = trim($term->name);
  if (!isset($term->vocabulary_machine_name)) {
    $vocabulary = taxonomy_vocabulary_load($term->vid);
    $term->vocabulary_machine_name = $vocabulary->machine_name;
  }

  // Load the stored entity, if any.
  if (!empty($term->tid) && !isset($term->original)) {
    $term->original = entity_load_unchanged('taxonomy_term', $term->tid);
  }

  field_attach_presave('taxonomy_term', $term);
  module_invoke_all('taxonomy_term_presave', $term);
  module_invoke_all('entity_presave', $term, 'taxonomy_term');

  if (empty($term->tid)) {
    $op = 'insert';
    $status = drupal_write_record('taxonomy_term_data', $term);
    field_attach_insert('taxonomy_term', $term);
    if (!isset($term->parent)) {
      $term->parent = array(0);
    }
  }
  else {
    $op = 'update';
    $status = drupal_write_record('taxonomy_term_data', $term, 'tid');
    field_attach_update('taxonomy_term', $term);
    if (isset($term->parent)) {
      db_delete('taxonomy_term_hierarchy')
        ->condition('tid', $term->tid)
        ->execute();
    }
  }

  if (isset($term->parent)) {
    if (!is_array($term->parent)) {
      $term->parent = array($term->parent);
    }
    $query = db_insert('taxonomy_term_hierarchy')
      ->fields(array('tid', 'parent'));
    foreach ($term->parent as $parent) {
      if (is_array($parent)) {
        foreach ($parent as $tid) {
          $query->values(array(
            'tid' => $term->tid,
            'parent' => $tid
          ));
        }
      }
      else {
        $query->values(array(
          'tid' => $term->tid,
          'parent' => $parent
        ));
      }
    }
    $query->execute();
  }

  // Reset the taxonomy term static variables.
  taxonomy_terms_static_reset();

  // Invoke the taxonomy hooks.
  module_invoke_all("taxonomy_term_$op", $term);
  module_invoke_all("entity_$op", $term, 'taxonomy_term');
  unset($term->original);

  return $status;
}