Structure Class Reference

Public Member Functions
	__construct (array $elements=null)
	importElements (array $elements)
	exportElements ()
	createElement ($elementId, array $data)
	getElement ($elementId)
	hasElement ($elementId)
	unsetElement ($elementId, $recursive=true)
	setAttribute ($elementId, $attribute, $value)
	getAttribute ($elementId, $attribute)
	renameElement ($oldId, $newId)
	setAsChild ($elementId, $parentId, $alias='', $position=null)
	unsetChild ($elementId, $alias=null)
	reorderChild ($parentId, $childId, $position)
	reorderToSibling ($parentId, $childId, $siblingId, $offset)
	getChildId ($parentId, $alias)
	getChildren ($parentId)
	getParentId ($childId)
	getChildAlias ($parentId, $childId)
	addToParentGroup ($childId, $groupName)
	getGroupChildNames ($parentId, $groupName)

Data Fields
const	PARENT = 'parent'
const	CHILDREN = 'children'
const	GROUPS = 'groups'

Protected Member Functions
	_assertParentRelation ($elementId)
	_getChildOffset ($parentId, $childId)
	_insertChild ($targetParentId, $elementId, $offset, $alias)

Protected Attributes
	$_elements = []

Detailed Description

An associative data structure, that features "nested set" parent-child relations

Definition at line 14 of file Structure.php.

Constructor & Destructor Documentation

__construct()

__construct

(

array

$elements = null

)

Set elements in constructor

Parameters

array

$elements

Definition at line 35 of file Structure.php.

    {
        if (null !== $elements) {
            $this->importElements($elements);
        }
    }

Member Function Documentation

_assertParentRelation()

_assertParentRelation (   $elementId )

protected

Verify relations of parent-child

Parameters

string

$elementId

Returns

void

Exceptions

LocalizedException

Definition at line 87 of file Structure.php.

    {
        $element = $this->_elements[$elementId];

        // element presence in its parent's nested set
        if (isset($element[self::PARENT])) {
            $parentId = $element[self::PARENT];
            $this->_assertElementExists($parentId);
            if (empty($this->_elements[$parentId][self::CHILDREN][$elementId])) {
                throw new LocalizedException(
                    new \Magento\Framework\Phrase(
                        'The "%1" is not in the nested set of "%2", causing the parent-child relation to break. '
                        . 'Verify and try again.',
                        [$elementId, $parentId]
                    )
                );
            }
        }

        // element presence in its children
        if (isset($element[self::CHILDREN])) {
            $children = $element[self::CHILDREN];
            $this->_assertArray($children);
            if ($children !== array_flip(array_flip($children))) {
                throw new LocalizedException(
                    new \Magento\Framework\Phrase(
                        'The "%1" format of children is invalid. Verify and try again.',
                        [var_export($children, 1)]
                    )
                );
            }
            foreach (array_keys($children) as $childId) {
                $this->_assertElementExists($childId);
                if (!isset(
                    $this->_elements[$childId][self::PARENT]
                ) || $elementId !== $this->_elements[$childId][self::PARENT]
                ) {
                    throw new LocalizedException(
                        new \Magento\Framework\Phrase(
                            'The "%1" doesn\'t have "%2" as parent, causing the parent-child relation to break. '
                            . 'Verify and try again.',
                            [$childId, $elementId]
                        )
                    );
                }
            }
        }
    }

_getChildOffset()

_getChildOffset (   $parentId,   $childId  )

protected

Calculate a relative offset of a child element in specified parent

Parameters

string	$parentId
string	$childId

Returns

int

Exceptions

LocalizedException

if specified elements have no parent-child relation

Definition at line 548 of file Structure.php.

    {
        $index = array_search($childId, array_keys($this->getChildren($parentId)));
        if (false === $index) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The "%1" is not a child of "%2". Resolve the issue and try again.',
                    [$childId, $parentId]
                )
            );
        }
        return $index;
    }

_insertChild()

_insertChild (   $targetParentId,   $elementId,   $offset,   $alias  )

protected

Insert an existing element as a child to existing element

The element must not be a child to any other element The target parent element must not have it as a child already

Offset – into which position to insert: 0 – set as 1st 1, 2 – after 1st, second, etc... -1, -2 – before last, before second last, etc... null – set as last

Parameters

string	$targetParentId
string	$elementId
int | null	$offset
string	$alias

Returns

void

Exceptions

LocalizedException

Definition at line 600 of file Structure.php.

    {
        $alias = $alias ?: $elementId;

        // validate
        $this->_assertElementExists($elementId);
        if (!empty($this->_elements[$elementId][self::PARENT])) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The element "%1" can\'t have a parent because "%2" is already the parent of "%1".',
                    [$elementId, $this->_elements[$elementId][self::PARENT]]
                )
            );
        }
        $this->_assertElementExists($targetParentId);
        $children = $this->getChildren($targetParentId);
        if (isset($children[$elementId])) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The element "%1" is already a child of "%2".',
                    [$elementId, $targetParentId]
                )
            );
        }
        if (false !== array_search($alias, $children)) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The element "%1" can\'t have a child because "%1" already has a child with alias "%2".',
                    [$targetParentId, $alias]
                )
            );
        }

        // insert
        if (null === $offset) {
            $offset = count($children);
        }
        $this->_elements[$targetParentId][self::CHILDREN] = array_merge(
            array_slice($children, 0, $offset),
            [$elementId => $alias],
            array_slice($children, $offset)
        );
        $this->_elements[$elementId][self::PARENT] = $targetParentId;
    }

addToParentGroup()

addToParentGroup	(		$childId,
			$groupName
	)

Add element to parent group

Parameters

string	$childId
string	$groupName

Returns

bool

Definition at line 505 of file Structure.php.

    {
        $parentId = $this->getParentId($childId);
        if ($parentId) {
            $this->_assertElementExists($parentId);
            $this->_elements[$parentId][self::GROUPS][$groupName][$childId] = $childId;
            return true;
        }
        return false;
    }

createElement()

createElement	(		$elementId,
		array	$data
	)

Create new element

Parameters

string	$elementId
array	$data

Returns

void

Exceptions

LocalizedException

if an element with this id already exists

Definition at line 154 of file Structure.php.

    {
        if (isset($this->_elements[$elementId])) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase('An element with a "%1" ID already exists.', [$elementId])
            );
        }
        $this->_elements[$elementId] = [];
        foreach ($data as $key => $value) {
            $this->setAttribute($elementId, $key, $value);
        }
    }

exportElements()

exportElements

(

)

Dump all elements

Returns

array

Definition at line 141 of file Structure.php.

    {
        return $this->_elements;
    }

getAttribute()

getAttribute	(		$elementId,
			$attribute
	)

Get element attribute

Parameters

string	$elementId
string	$attribute

Returns

mixed

Definition at line 248 of file Structure.php.

    {
        $this->_assertElementExists($elementId);
        if (isset($this->_elements[$elementId][$attribute])) {
            return $this->_elements[$elementId][$attribute];
        }
        return false;
    }

getChildAlias()

getChildAlias	(		$parentId,
			$childId
	)

Get element alias by name

Parameters

string	$parentId
string	$childId

Returns

string|bool

Definition at line 490 of file Structure.php.

    {
        if (isset($this->_elements[$parentId][self::CHILDREN][$childId])) {
            return $this->_elements[$parentId][self::CHILDREN][$childId];
        }
        return false;
    }

getChildId()

getChildId	(		$parentId,
			$alias
	)

Get child ID by parent ID and alias

Parameters

string	$parentId
string	$alias

Returns

string|bool

Definition at line 451 of file Structure.php.

    {
        if (isset($this->_elements[$parentId][self::CHILDREN])) {
            return array_search($alias, $this->_elements[$parentId][self::CHILDREN]);
        }
        return false;
    }

getChildren()

getChildren

(

$parentId

)

Get all children

Returns in format 'id' => 'alias'

Parameters

string

$parentId

Returns

array

Definition at line 467 of file Structure.php.

    {
        return $this->_elements[$parentId][self::CHILDREN] ?? [];
    }

getElement()

getElement

(

$elementId

)

Get existing element

Parameters

string

$elementId

Returns

array|bool

Definition at line 173 of file Structure.php.

    {
        return $this->_elements[$elementId] ?? false;
    }

getGroupChildNames()

getGroupChildNames	(		$parentId,
			$groupName
	)

Get element IDs for specified group

Note that it is expected behavior if a child has been moved out from this parent, but still remained in the group of old parent. The method will return only actual children. This is intentional, in case if the child returns back to the old parent.

Parameters

string	$parentId	Name of an element containing group
string	$groupName

Returns

array

Definition at line 527 of file Structure.php.

    {
        $result = [];
        if (isset($this->_elements[$parentId][self::GROUPS][$groupName])) {
            foreach ($this->_elements[$parentId][self::GROUPS][$groupName] as $childId) {
                if (isset($this->_elements[$parentId][self::CHILDREN][$childId])) {
                    $result[] = $childId;
                }
            }
        }
        return $result;
    }

getParentId()

getParentId

(

$childId

)

Get name of parent element

Parameters

string

$childId

Returns

string|bool

Definition at line 478 of file Structure.php.

    {
        return $this->_elements[$childId][self::PARENT] ?? false;
    }

hasElement()

hasElement

(

$elementId

)

Whether specified element exists

Parameters

string

$elementId

Returns

bool

Definition at line 184 of file Structure.php.

    {
        return isset($this->_elements[$elementId]);
    }

importElements()

importElements

(

array

$elements

)

Set elements from external source

Parameters

array

$elements

Returns

void

Exceptions

LocalizedException

if any format issues identified

Definition at line 49 of file Structure.php.

    {
        $this->_elements = $elements;
        foreach ($elements as $elementId => $element) {
            if (is_numeric($elementId)) {
                throw new LocalizedException(
                    new \Magento\Framework\Phrase("Element ID must not be numeric: '%1'.", [$elementId])
                );
            }
            $this->_assertParentRelation($elementId);
            if (isset($element[self::GROUPS])) {
                $groups = $element[self::GROUPS];
                $this->_assertArray($groups);
                foreach ($groups as $groupName => $group) {
                    $this->_assertArray($group);
                    if ($group !== array_flip($group)) {
                        throw new LocalizedException(
                            new \Magento\Framework\Phrase(
                                '"%2" is an invalid format of "%1" group. Verify the format and try again.',
                                [$groupName, var_export($group, 1)]
                            )
                        );
                    }
                    foreach ($group as $groupElementId) {
                        $this->_assertElementExists($groupElementId);
                    }
                }
            }
        }
    }

renameElement()

renameElement	(		$oldId,
			$newId
	)

Rename element ID

Parameters

string	$oldId
string	$newId

Returns

$this

Exceptions

LocalizedException

if trying to overwrite another element

Definition at line 265 of file Structure.php.

    {
        $this->_assertElementExists($oldId);
        if (!$newId || isset($this->_elements[$newId])) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase('An element with a "%1" ID is already defined.', [$newId])
            );
        }

        // rename in registry
        $this->_elements[$newId] = $this->_elements[$oldId];

        // rename references in children
        if (isset($this->_elements[$oldId][self::CHILDREN])) {
            foreach (array_keys($this->_elements[$oldId][self::CHILDREN]) as $childId) {
                $this->_assertElementExists($childId);
                $this->_elements[$childId][self::PARENT] = $newId;
            }
        }

        // rename key in its parent's children array
        if (isset($this->_elements[$oldId][self::PARENT]) && ($parentId = $this->_elements[$oldId][self::PARENT])) {
            $alias = $this->_elements[$parentId][self::CHILDREN][$oldId];
            $offset = $this->_getChildOffset($parentId, $oldId);
            unset($this->_elements[$parentId][self::CHILDREN][$oldId]);
            $this->setAsChild($newId, $parentId, $alias, $offset);
        }

        unset($this->_elements[$oldId]);
        return $this;
    }

reorderChild()

reorderChild	(		$parentId,
			$childId,
			$position
	)

Reorder a child element relatively to specified position

Returns new position of the reordered element

Parameters

string	$parentId
string	$childId
int | null	$position

Returns

int

See also

_insertChild() for position explanation

Definition at line 373 of file Structure.php.

    {
        $alias = $this->getChildAlias($parentId, $childId);
        $currentOffset = $this->_getChildOffset($parentId, $childId);
        $offset = $position;
        if ($position > 0) {
            if ($position >= $currentOffset + 1) {
                $offset -= 1;
            }
        } elseif ($position < 0) {
            if ($position < $currentOffset + 1 - count($this->_elements[$parentId][self::CHILDREN])) {
                if ($position === -1) {
                    $offset = null;
                } else {
                    $offset += 1;
                }
            }
        }
        $this->unsetChild($childId)->_insertChild($parentId, $childId, $offset, $alias);
        return $this->_getChildOffset($parentId, $childId) + 1;
    }

reorderToSibling()

reorderToSibling	(		$parentId,
			$childId,
			$siblingId,
			$offset
	)

Reorder an element relatively to its sibling

$offset possible values: 1, 2 – set after the sibling towards end – by 1, by 2 positions, etc -1, -2 – set before the sibling towards start – by 1, by 2 positions, etc...

Both $childId and $siblingId must be children of the specified $parentId Returns new position of the reordered element

Parameters

string	$parentId
string	$childId
string	$siblingId
int	$offset

Returns

int

Definition at line 411 of file Structure.php.

    {
        $this->_getChildOffset($parentId, $childId);
        if ($childId === $siblingId) {
            $newOffset = $this->_getRelativeOffset($parentId, $siblingId, $offset);
            return $this->reorderChild($parentId, $childId, $newOffset);
        }
        $alias = $this->getChildAlias($parentId, $childId);
        $newOffset = $this->unsetChild($childId)->_getRelativeOffset($parentId, $siblingId, $offset);
        $this->_insertChild($parentId, $childId, $newOffset, $alias);
        return $this->_getChildOffset($parentId, $childId) + 1;
    }

setAsChild()

setAsChild	(		$elementId,
			$parentId,
			$alias = '',
			$position = null
	)

Set element as a child to another element

Parameters

string	$elementId
string	$parentId
string	$alias
int | null	$position

See also

_insertChild() for position explanation

Returns

void

Exceptions

LocalizedException

if attempting to set parent as child to its child (recursively)

Definition at line 308 of file Structure.php.

    {
        if ($elementId == $parentId) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The "%1" was incorrectly set as a child to itself. Resolve the issue and try again.',
                    [$elementId]
                )
            );
        }
        if ($this->_isParentRecursively($elementId, $parentId)) {
            throw new LocalizedException(
                new \Magento\Framework\Phrase(
                    'The "%3" cannot be set as child to "%1" because "%1" is a parent of "%2" recursively. '
                    . 'Resolve the issue and try again.',
                    [$elementId, $parentId, $elementId]
                )
            );
        }
        $this->unsetChild($elementId);
        unset($this->_elements[$parentId][self::CHILDREN][$elementId]);
        $this->_insertChild($parentId, $elementId, $position, $alias);
    }

setAttribute()

setAttribute	(		$elementId,
			$attribute,
			$value
	)

Set an arbitrary value to specified element attribute

Parameters

string	$elementId
string	$attribute
mixed	$value

Exceptions

Definition at line 226 of file Structure.php.

    {
        $this->_assertElementExists($elementId);
        switch ($attribute) {
            case self::PARENT:
                // break is intentionally omitted
            case self::CHILDREN:
            case self::GROUPS:
                throw new \InvalidArgumentException("The '{$attribute}' attribute is reserved and can't be set.");
            default:
                $this->_elements[$elementId][$attribute] = $value;
        }
        return $this;
    }

unsetChild()

unsetChild	(		$elementId,
			$alias = null
	)

Unset element as a child of another element

Note that only parent-child relations will be deleted. Element itself will be retained. The method is polymorphic: 1 argument: element ID which is supposedly a child of some element 2 arguments: parent element ID and child alias

Parameters

string	$elementId	ID of an element or its parent element
string | null	$alias

Returns

$this

Definition at line 344 of file Structure.php.

    {
        if (null === $alias) {
            $childId = $elementId;
        } else {
            $childId = $this->getChildId($elementId, $alias);
        }
        $parentId = $this->getParentId($childId);
        unset($this->_elements[$childId][self::PARENT]);
        if ($parentId) {
            unset($this->_elements[$parentId][self::CHILDREN][$childId]);
            if (empty($this->_elements[$parentId][self::CHILDREN])) {
                unset($this->_elements[$parentId][self::CHILDREN]);
            }
        }
        return $this;
    }

unsetElement()

unsetElement	(		$elementId,
			$recursive = true
	)

Remove element with specified ID from the structure

Can recursively delete all child elements. Returns false if there was no element found, therefore was nothing to delete.

Parameters

string	$elementId
bool	$recursive

Returns

bool

Definition at line 199 of file Structure.php.

    {
        if (isset($this->_elements[$elementId][self::CHILDREN])) {
            foreach (array_keys($this->_elements[$elementId][self::CHILDREN]) as $childId) {
                $this->_assertElementExists($childId);
                if ($recursive) {
                    $this->unsetElement($childId, $recursive);
                } else {
                    unset($this->_elements[$childId][self::PARENT]);
                }
            }
        }
        $this->unsetChild($elementId);
        $wasFound = isset($this->_elements[$elementId]);
        unset($this->_elements[$elementId]);
        return $wasFound;
    }

Field Documentation

$_elements

$_elements = []

protected

Definition at line 28 of file Structure.php.

CHILDREN

const CHILDREN = 'children'

Definition at line 21 of file Structure.php.

GROUPS

const GROUPS = 'groups'

Definition at line 23 of file Structure.php.

PARENT

const PARENT = 'parent'

Reserved keys for storing structural relations

Definition at line 19 of file Structure.php.

---

The documentation for this class was generated from the following file:

• vendor/magento/framework/Data/Structure.php