Find elements in an instance

In almost any scenario it is necessary to access and use values from an instance document. This page reviews some of the features available to help access instance document values. In the context of this project, they are referred to as 'entries'.

###Load an instance document

The start point is to load an instance document which will be something like this:

/**
 * @var XBRL_Instance
 */
$instance = null;
$result = XBRL_Instance::FromInstanceDocument( 'instance doc.xml', null, $instance );

###InstanceElementsFilter

The elements and values are available by calling the getElements function. This function returns an 'InstanceElementsFilter' instance which provides functions to filter the elements in the instance document.

/**
 * @var InstanceElementsFilter
 */
$elements = $instance->getElements();

Access to the raw elements is possible using the getElements function:

$elements = $elements->getElements();

###Entries

The elements array is indexed by the name of the element. This name is the name given in the taxonomy element.

Each element can have zero or more entries. Each entry might be for a different context. But if the loaded instance document source is, say, an iXBRL document where the same value is tagged in different sections of the source document then the entries might contain multiple copies of the same value.

In case this is a possibility the 'InstanceElementsFilter' class includes a function called UniqueElementEntries return elements with only distinct entries.

$elements = $elements->UniqueElementEntries();

###Filtering

Using 'InstanceElementsFilter' class functions the element list can be filtered in different ways:

Function	Comment
ElementsByName	Return the elements that match by a list of one or more names
ElementsByContexts	Return the elements that match by a list of one or more contexts
ElementsByNamespaces	Return the elements that match by a list of one or more namespaces
ElementsByItemType	Return the elements that match by a list of one or more item types

Each function accepts either a comma delimited list of items or an array of items. Here is an example that will return elements and their entries for three named elements. The list is provided as an array but could equally well be a comma delimited list.

$namedElements = $elements->ElementsByName(
	array( 
		'UKCompaniesHouseRegisteredNumber',
		'BusinessReportName',
		'ProfitLossForPeriod',
	)
);

Of course you can always retrieve the raw list of elements and use the PHP language features to create a custom filter.

###Chaining filters

The UniqueElementEntries function and each of the filter functions return a 'InstanceElementsFilter' instance containing only the filtered elements. This means they can be chained together to create a composite expression such as:

$rawElements = $elements->UniqueElementEntries()->ElementsByContexts('FY')->getElements();

###Other InstanceElementsFilter functions

Function	Comment
count	Returns the count of elements and will be affected by each filter
getItemTypes	Returns an array containing a list of unique element item types
getNamespaces	Returns an array containing a list of unique element item namespaces
getSubstitutionGroups	Returns an array containing a list of unique element substitution groups