CHAPTER 15 ■ WORKING WITH TAXONOMY

taxonomy_term_delete($tid)

The taxonomy_term_delete($tid) function deletes a term; the $tid parameter is the term ID. If a term is in a hierarchical vocabulary and has children, the children will be deleted as well, unless a child term has multiple parents.

Retrieving Information About Term Hierarchy

When you are working with hierarchical vocabularies, the functions in the following sections can come in handy.

taxonomy_get_parents($tid, $key)

This function finds the immediate parents of a term; the $tid parameter is the term ID. The $key parameter defaults to tid and is a column of the term_data table (tid, vid, name, description, weight). taxonomy_get_parents($tid, $key) returns an associative array of term objects, keyed by $key.

taxonomy_get_parents_all($tid)

This function finds all ancestors of a term; the $tid parameter is the term ID. The function returns an array of term objects.

taxonomy_get_children($tid, $vid, $key)

The taxonomy_get_children($tid, $vid, $key) function finds all children of a term. The $tid parameter is the term ID. The $vid parameter is optional; if a vocabulary ID is passed, the children of the term will be restricted to that vocabulary (note that this is only important for terms that have multiple parents in different vocabularies, a rare occurrence). The $key parameter defaults to tid and is a column of the term_data table (tid, vid, name, description, weight). This function returns an associative array of term objects, keyed by $key.

taxonomy_get_tree($vid, $parent, $max_depth, $load_entities = FALSE)

This function generates a hierarchical representation of a vocabulary. The $vid parameter is the vocabulary ID of the vocabulary for which to generate the tree. You can specify the $parent parameter if you don’t want the entire tree for a vocabulary and want only that part of the tree that exists under the term ID specified by $parent. The $max_depth parameter is an integer indicating the number of levels of the tree to return, and it defaults to NULL, indicating all levels. The $load_entities parameter will cause a complete load of each term object if set to TRUE. This function returns an array of term objects with depth and parent keys added. The depth key is an integer indicating the level of hierarchy at which the term exists in the tree, and the parents key is an array of term IDs of a term’s parents. For example, let’s get the results for the vocabulary shown in Table 15-3, which happens to be vocabulary ID 2:

359

360

CHAPTER 15 ■ WORKING WITH TAXONOMY

[parents] => Array ( [0] => 1 )

)

[2] => stdClass Object ( [tid] => 5

[vid] => 2 [name] => Toronto

[description] => Diversity Our Strength. [weight] => 0

[depth] => 2 [parents] => Array (

[0] => 4 )

)

[3] => stdClass Object ( [tid] => 2

[vid] => 2

[name] => British Columbia [description] => Splendor sine occasu. [format] => 3

[weight] => 0 [depth] => 1

361

CHAPTER 15 ■ WORKING WITH TAXONOMY

[parents] => Array ( [0] => 1 )

)

[4] => stdClass Object ( [tid] => 3

[vid] => 2

[name] => Vancouver

[description] => By Land, Sea and Air We Prosper. [format] => 3

[weight] => 0 [depth] => 2 [parents] => Array (

[0] => 2 )

)

)

Finding Nodes with Certain Terms

Sometimes, you want to have an easy way to query which nodes have certain terms or output the results of such a query. The taxonomy_select_nodes($tids, $pager, $limit, $order) helps you accomplish that goal. This function finds nodes that match conditions by building and executing a database query based on given parameters. It returns a resource identifier pointing to the query results. The $tids parameter is an array of term IDs. The $limit parameter indicates the maximum number of nodes to find. Setting $limit to FALSE returns all nodes (no limit). The $pager parameter is a Boolean value indicating whether resulting nodes will be used with a pager, and it defaults to TRUE. You might set $pager to FALSE if you were generating an XML feed. The $order parameter contains an associative array of conditions that will be applied to the SQL statement—for example, ‘t.created’ => ‘DESC’ will sort the results in descending order based on the date created.

If you’re searching for many terms, this function can be database-intensive.

362