Finding a node

Although it is possible to navigate a hierarchy using the recursive method this method is most suited to tasks that affect all or a substantial proportion of the nodes. It is not an ideal method when the requirement is to find a specific node because on average half of all the nodes must be traversed to find the one.

This is OK when there are a small number of nodes or if only one node need to be retrieved. But if the requirement is to find a succession of nodes, perhaps scattered throughout the hierarchy, then search half of all the nodes each time is not efficient.

Instead, compiled taxonomies include an index that allows a caller to locate a node in a the hierarchy more efficiently because the algorithm used to find the node is not affected by the size of the hierarcy.

---

Below is an example of using the path to locate rows. Of course the first thing is to access a taxonomy that includes some form of hierarchy such as a presentation linkbase:

$xbrl = \XBRL::load_taxonomy( '<some file>' );

Now the presentation roles can be accessed.

$roles = $xbrl->getPresentationRoleRefs();

This is the label of the node to be found.

$id = 'uk-gaap_ShareholderFunds';

There are many ways to tack the next step. In this case it is to create a list of paths. The element could exist in several roles. For example, in the UK GAAP taxonomy the shareholder funds element appears in the balance sheet role (twice) and in the reconciliation of shareholder funds role (also twice).

$locatedPaths = array_reduce( $roles, function( $carry, $role ) use( $id ) {
	if ( ! isset( $role['paths'] ) ) return $carry;
	if ( ! isset( $role['paths'][ $id ] ) ) return $carry;;

	$carry[ $role['roleUri'] ] = $role['paths'][ $id ];
	return $carry;
}, array() );

Now find and process each node. $locatedPaths is an array of arrays.

foreach ( $locatedPaths as $roleKey => $paths )
{
	foreach ( $paths as $key => $path )
	{

The function $xbrl->processNode() is able to take a path and find the corresponding node in a set of nodes in a hierarchy.

• @param array $nodes A set of $node arrays
• @param string $path The path to the element in the $node hierarchy
• @param function $callback If supplied this will be called once for every node located.
• @return bool True if the element is found

		$success = $xbrl->processNode( $roles[ $roleKey ]['hierarchy'], $path, function( &$node ) {
			$node['yyy'] = 'zzz';
		} );
	}
}

---

The callback receives the node as a reference parameter. This means the callback is able to modify the hierarchy node.