function taxonomy_term_save

7.x taxonomy.module taxonomy_term_save($term)

Saves a term object to the database.


$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.

14 calls to taxonomy_term_save()
EntityCrudHookTestCase::testTaxonomyTermHooks in drupal/modules/simpletest/tests/entity_crud_hook_test.test
Tests hook invocations for CRUD operations on taxonomy terms.
forum_enable in drupal/modules/forum/forum.install
Implements hook_enable().
forum_form_submit in drupal/modules/forum/
Form submission handler for forum_form_forum() and forum_form_container().
TaxonomyTermFunctionTestCase::testTaxonomyVocabularyTree in drupal/modules/taxonomy/taxonomy.test
Test a taxonomy with terms that have multiple parents of different depths.
TaxonomyTermIndexTestCase::testTaxonomyTermHierarchyBreadcrumbs in drupal/modules/taxonomy/taxonomy.test
Tests that there is a link to the parent term on the child term page.

... See full list


drupal/modules/taxonomy/taxonomy.module, line 621
Enables the organization of content into categories.


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) {
            'tid' => $term->tid,
            'parent' => $tid,
      else {
          'tid' => $term->tid,
          'parent' => $parent,

  // Reset the taxonomy term static variables.

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

  return $status;