Method findGroup

/**
 * Method to get a form field group represented as an XML element object.
 *
 * @param   string  $group  The dot-separated form group path on which to find the group.
 *
 * @return  \SimpleXMLElement[]|boolean  An array of XML element objects for the group or boolean false on error.
 *
 * @since   1.7.0
 */
protected function &findGroup($group)
{
    $false = false;
    $groups = [];
    $tmp = [];
    // Make sure there is a valid Form XML document.
    if (!$this->xml instanceof \SimpleXMLElement) {
        throw new \UnexpectedValueException(sprintf('%s::%s `xml` is not an instance of SimpleXMLElement', \get_class($this), __METHOD__));
    }
    // Make sure there is actually a group to find.
    $group = explode('.', $group);
    if (!empty($group)) {
        // Get any fields elements with the correct group name.
        $elements = $this->xml->xpath('//fields[@name="' . (string) $group[0] . '" and not(ancestor::field/form/*)]');
        // Check to make sure that there are no parent groups for each element.
        foreach ($elements as $element) {
            if (!$element->xpath('ancestor::fields[@name]')) {
                $tmp[] = $element;
            }
        }
        // Iterate through the nested groups to find any matching form field groups.
        for ($i = 1, $n = \count($group); $i < $n; $i++) {
            // Initialise some loop variables.
            $validNames = \array_slice($group, 0, $i + 1);
            $current = $tmp;
            $tmp = [];
            // Check to make sure that there are no parent groups for each element.
            foreach ($current as $element) {
                // Get any fields elements with the correct group name.
                $children = $element->xpath('descendant::fields[@name="' . (string) $group[$i] . '"]');
                // For the found fields elements validate that they are in the correct groups.
                foreach ($children as $fields) {
                    // Get the group names as strings for ancestor fields elements.
                    $attrs = $fields->xpath('ancestor-or-self::fields[@name]/@name');
                    $names = array_map('strval', $attrs ?: []);
                    // If the group names for the fields element match the valid names at this
                    // level add the fields element.
                    if ($validNames == $names) {
                        $tmp[] = $fields;
                    }
                }
            }
        }
        // Only include valid XML objects.
        foreach ($tmp as $element) {
            if ($element instanceof \SimpleXMLElement) {
                $groups[] = $element;
            }
        }
    }
    return $groups;
}