Shapes : Add moveShape(), and say how shapes stack

[dkulyk]

Description

The shapes of a container are written in the order the collection holds them, and that order is the stacking order -- the first shape is at the back, the last is in front. Nothing could change that order but rebuilding the array and handing it back through setShapeCollection(), which is what the reporter does today:

Now i've fixed this with changing keys in the array but can there be a function added for this?

Remove-and-re-add is not a substitute either: unsetShape() is a bare unset(), so it leaves a hole in the keys and addShape()'s [] = then appends at max + 1.

moveShape(AbstractShape $shape, int $index) is moveSlide() (#966) one level down, with the same two guards and the same array_splice in one step. It lives on the ShapeCollection trait rather than on AbstractSlide, so a slide, a slide layout, a slide master, a Group and the note of a slide all get it at once.

$image = $slide->createDrawingShape();
$text = $slide->createRichTextShape();

$slide->moveShape($image, 1);   // the image is now in front of the text

The collection is reindexed before the search, because after unsetShape() a key no longer says the place a shape sits in and array_splice() counts places, not keys.

Fixes #866

Checklist:

• I have run composer run-script check --timeout=0 and no errors were reported

phpstan reports [OK] No errors, php-cs-fixer 0 of 302, and the suite is green at 1149 tests, 9264 assertions.

• The new code is covered by unit tests

Four tests in SlideTest: a move to the back and to the front, a move after unsetShape() has left a hole in the keys, a shape the container does not hold (InvalidParameterException) and an index past the end (OutOfBoundsException).

• I have updated the documentation to describe the changes

A Stacking order section in docs/usage/shapes/introduction.md, which said nothing about stacking order before.

• I have added a changelog entry

An entry under ## Enhancements in docs/changes/1.3.0.md.

[coveralls]

coverage: 94.127% (+0.004%) from 94.123% — sapientpro:feat/move-shape into PHPOffice:master

[Progi1984]

Suggested change

	public function moveShape(AbstractShape $shape, int $index)
	public function moveShape(AbstractShape $shape, int $index): self

[Progi1984]

Small feedback (and rebase if needed)