Taxonomy Rollup

About this Module

Taxonomy Rollup provides a service that allows rolling up of taxonomy terms to their parent terms, either all the way up to the top ancestor or to a specific level of a vocabulary. It is useful for categorisation, mapping, transforming etc.

Example

Taxonomy: staff_hierarchy

- Hospital Staff (1)
  - Medical Staff (2)
     - Surgeon (3)
     - Nurse (4)
     - Doctor (5)
  - Non Medical Staff (6)
     - Orderly (7)
- Customer Service Staff (8)
   - Store Worker (9)
   - Telephone Operator (10)
- Transport Staff (11)
   - Bus (12)
      - Bus Driver (13)
      - Bus Ticket Collector (14)
   - Train (15)
      - Train Driver (16)

Then in your code:

  // Get the service.
  $taxonomy_rollup = \Drupal::service('taxonomy_rollup.service');

  // Hospital Staff.
  $taxonomy_rollup->getRollupTermNameByTermName('staff_hierarchy', 'Doctor');
  $taxonomy_rollup->getRollupNameByTid(5);
  // getRollupNameByTid will be renamed to getRollupTermNameByTid in next release.


  // Medical Staff (max height 1).
  $taxonomy_rollup->getRollupTermNameByTermName('staff_hierarchy', 'Doctor', 1):
  $taxonomy_rollup->getRollupNameByTid(5, 1);

  // Transport Staff.
  $taxonomy_rollup->getRollupTermNameByTermName('staff_hierarchy', 'Bus');

  // Some made up term name.
  $taxonomy_rollup->getRollupTermNameByTermName('staff_hierarchy', 'Some made up term name');

  // 11.
  $taxonomy_rollup->getRollupTidByTid(16);


/**
*  Methods in TaxonomyRollupServiceInterface:
*  
*  getTidFromName($vid, $term_name);
*  getRollupTermByTermName($vid, $term_name, $maxHeight = -1);
*  getRollupTermNameByTermName($vid, $term_name, $maxHeight = -1);
*  getRollupNameByTid($tid, $maxHeight = -1);
*  getRollupTidByTid($tid, $maxHeight = -1);
*  getRollupTermByTid($tid, $maxHeight = -1);
*  
**/

Other functions

There are also functions to return the Term Object, Term ID and search by Term ID. The max height parameter specifies how many levels up the hierarchy to travel (by default it ascends to the top of the tree).

Error handling

When searching by Term name, terms that are not found in the vocabulary or ambiguous terms (terms which have the same name in multiple levels of the same vocabulary) are logged and the term name parameter is returned. Term IDs eliminate ambiguity, so its best to use a Term ID if possible.

When requesting Term ID, if no candidate is found, -1 is returned and the fact is logged.

When requesting the term object, if no candidate is found, NULL is returned and the fact is logged.