Working with dimensions

The 'XBRL' class provides a number of classes to access dimension information. Dimension information is defined in the definition linkbase.

Primary items

The XBRL Dimensional Taxonomy (XDT) specification includes this definition in section 2.1: The Dimensional relationship set (DRS) is the set of consecutive relationships [Def, 2] that represents the relationships between a primary item declaration [Def, 1] and its multidimensional metadata.

Not all elements in a taxonomy schema are primary items. Only those at the root of a DRS are primary items. Those elements that are primary items can be retrieved using the call getDefinitionPrimaryItems. This will select primary items associated with any extended link role (ELR). If the role is known in advance the call getDefinitionRolePrimaryItems can be used to retrieve primary items for a single role.

These functions return an array of primary items. Each element of the array has this structure:

[role_xyz]
    [label] myschema.xsd#primaryitem_abc
    [hypercubes]
        [0] hypercube_1
    [roleUri] role_xyz
    [parents]
        [primaryitem_parent_1]
            [arcrole] http://xbrl.org/int/dim/arcrole/domain-member
            [order] 
            [use]
            [title]
            [priority]
            [nodeclass]
            [usable]
[roles]
    [role_xyz]

Where the structure may be repeated when function getDefinitionPrimaryItems is called. The repetition will reflect that the primary item may appear in more than one role.

In this example 'role_xyz' is the id of a role in which the primary item with id 'primaryitem_abc' appears. In this role the primary item is associated with one hypercube with id 'hypercube_1. The primary item has one parent, another primary item, with id 'primaryitem_parent_1'. The sub-elements are the details of the relationship between 'primaryitem_parent_1' and 'primaryitem_abc'

Dimensional Relationship Set

It is possible to use the function getPrimaryItemDRS to access the dimensional relationship set for any primary item returned by getDefinitionPrimaryItems or getDefinitionRolePrimaryItems. Here is an example of accessing DRS information.

$instance = XBRL_Instance::FromInstanceDocument( 'my_instance_document.xml' );
$primaryItems = $instance->getInstanceTaxonomy()->getDefinitionPrimaryItems( );
foreach ( $instance->getElements()->getElements() as $factId => $fact )
{
    if ( count( $primaryItems ) )
    {
        $drsHypercubes = null;
        foreach ( $fact as $entryKey => $entry )
        {
            if ( is_null( $drsHypercubes ) )
            {
                $primaryItem = isset( $primaryItems[ $entry['label'] ] ) ? $primaryItems[ $entry['label'] ] : false;
                if ( ! $primaryItem ) continue;
                $drsHypercubes = $instance->getInstanceTaxonomy()->getPrimaryItemDRS( $primaryItem );
            }
        }
    }
}

This example begins by creating an instance from an instance document. When the static function XBRL_Instance::FromInstanceDocument is called it accesses the taxonomy associated with the instance document. The taxonomy class instance is available through the instance function $instance->getInstanceTaxonomy(). Using this the primary items from the taxonomy can be accessed.

Not all of the primary items are relevant for the instance document so in the example facts from the instance document are retrieved using the $instance->getElements()->getElements() function. No, that double use of 'getElements' is not a mistake. The first use of 'getElements' returns an instance of the class 'InstanceElementsFilter' which, as the name suggests, allows various filters to be applied to the facts available in the instance document. The second returns the result of the filter. In this case there is no filter so it will return all the facts.

The remainder of the example iterates over the list of facts and calls $instance->getInstanceTaxonomy()->getPrimaryItemDRS to resolve the dimensional relationship set for each primary item.

Dimension components

All the definition information can be accessed the getDefinitionRoleRefs function:

$roles = $xbrl->getDefinitionRoleRefs();

The function returns an array indexed by role. So the list of taxonomy roles can be retrieved like this:

$roles = array_keys( $roles );

But this is not the way to get dimension information. The 'XBRL' class provides two groups of functions.

---

This group of functions returns all items in the taxonomy.

Function	Comment
getDefinitionDimensionMembers	These are elements in a definition linkbase that are not primary items
getDefinitionPrimaryItems	Returns a list of all the primary items in the taxonomy
getDefinitionHypercubes	Returns a list of the hypercubes in the taxonomy
getDefinitionDimensions	Returns a list of the dimensions in the taxonomy

---

This group of function returns items for a specific role.

Function	Comment
getDefinitionRoleDimensionMembers	These are elements in a definition linkbase that are not primary items
getDefinitionRolePrimaryItems	Returns a list of all the primary items for the role
getDefinitionRoleHypercubes	Returns a list of the hypercubes in the role
getDefinitionRoleDimensions	Returns a list of the dimensions in the role