Presentation : Added ability to add a slide at any position

Author: Progi1984

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+### Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
+
+Fixes # (issue)
+
+### Checklist:
+
+- [ ] My CI is :green_circle:
+- [ ] I have covered by unit tests my new code (check build/coverage for coverage report)
+- [ ] I have updated the [documentation](https://github.com/PHPOffice/PHPPresentation/tree/develop/docs) to describe the changes
+- [ ] I have updated the [changelog](https://github.com/PHPOffice/PHPPresentation/blob/develop/docs/changes/1.1.0.md)

.github/workflows/php.yml

@@ -63,7 +63,7 @@ jobs:
             run: ./vendor/bin/phpstan analyse -c phpstan.neon.dist
 
   phpunit:
-    name: PHPUnit
+    name: PHPUnit ${{ matrix.php }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -75,14 +75,19 @@ jobs:
           with:
               php-version: ${{ matrix.php }}
               extensions: gd, xml, zip
-              coverage: xdebug
+              coverage: ${{ (matrix.php == '7.3') && 'xdebug' || 'none' }}
 
       -   uses: actions/checkout@v2
 
       -   name: Composer Install
           run: composer install --ansi --prefer-dist --no-interaction --no-progress
 
       -   name: Run phpunit
+          if: matrix.php != '7.3'
+          run: ./vendor/bin/phpunit -c phpunit.xml.dist --no-coverage
+
+      -   name: Run phpunit
+          if: matrix.php == '7.3'
           run: ./vendor/bin/phpunit -c phpunit.xml.dist --coverage-clover build/clover.xml
 
       -   name: Upload coverage results to Coveralls

docs/changes/1.1.0.md

@@ -35,6 +35,7 @@
 - Shadow : Support for Type Inner & Reflection - [@devX2712](https://github.com/devX2712) in [#788](https://github.com/PHPOffice/PHPPresentation/pull/787)
     - PowerPoint2007 Reader
     - PowerPoint2007 Writer 
+- Presentation : Added ability to add a slide at any position - [@Progi1984](https://github.com/Progi1984) in [#810](https://github.com/PHPOffice/PHPPresentation/pull/810)
 
 ## Bugfixes
 

docs/usage/slides/introduction.md

@@ -1,8 +1,38 @@
 # Introduction
 
-Slides are pages in a presentation. Slides are stored as a zero based array in `PHPPresentation` object. Use the method `createSlide` to create a new slide and retrieve the slide for other operation such as creating shapes for that slide.
+Slides are pages in a presentation. Slides are stored as a zero based array in `PHPPresentation` object. 
 
-## Name
+## Create slide
+
+Use the method `createSlide` to create a new slide and retrieve the slide for other operation such as creating shapes for that slide. The slide will be added at the end of slides collection.
+
+``` php
+<?php
+
+$slide = $presentation->createSlide();
+```
+
+## Add slide to a specific position
+
+Use the method `addSlide` to add an existing slide to a specific position. Without the parameter `$position`, it will be added at the end of slides collection.
+
+``` php
+<?php
+
+use PhpOffice\PhpPresentation\Slide;
+
+$slide = new Slide($presentation);
+## Add it before all slides
+$presentation->addSlide($slide, 0);
+## Add it to position 1
+$presentation->addSlide($slide, 1);
+## Add it after all slides
+$presentation->addSlide($slide);
+```
+
+## Properties
+
+### Name
 
 By default, a slide has not a name.
 You can define it with the method `setName`.
@@ -14,7 +44,7 @@ $slide = $presentation->createSlide();
 $slide->setName('Title of the slide');
 ```
 
-## Visibility
+### Visibility
 
 By default, a slide is visible.
 You can define it with the method `setIsVisible`.

phpstan.neon.dist

@@ -18,6 +18,7 @@ parameters:
     ## PHP 8.0 & GdImage
     - '#^Parameter \#1 \$value of method PhpOffice\\PhpPresentation\\Shape\\Drawing\\Gd::setImageResource\(\) expects resource\|null, GdImage\ given\.#'
     - '#^Parameter \#1 \$value of method PhpOffice\\PhpPresentation\\Shape\\Drawing\\Gd::setImageResource\(\) expects resource\|null, GdImage\|false given\.#'
+    - '#^Parameter \#1 \$value of method PhpOffice\\PhpPresentation\\Shape\\Drawing\\Gd::setImageResource\(\) expects resource\|null, \(GdImage\|false\) given\.#'
     - '#^Parameter \#1 \$image of function imagesx expects GdImage, resource given\.#'
     - '#^Parameter \#1 \$image of function imagesy expects GdImage, resource given\.#'
     - '#^Parameter \#1 \$image of function imagealphablending expects GdImage, resource given\.#'

src/PhpPresentation/PhpPresentation.php

@@ -165,9 +165,13 @@ public function createSlide(): Slide
     /**
      * Add slide.
      */
-    public function addSlide(Slide $slide): Slide
+    public function addSlide(Slide $slide, int $index = -1): Slide
     {
-        $this->slideCollection[] = $slide;
+        if ($index > -1) {
+            array_splice($this->slideCollection, $index, 0, [$slide]);
+        } else {
+            $this->slideCollection[] = $slide;
+        }
 
         return $slide;
     }

src/PhpPresentation/Shape/RichText/TextElementInterface.php

@@ -19,6 +19,8 @@
 
 namespace PhpOffice\PhpPresentation\Shape\RichText;
 
+use PhpOffice\PhpPresentation\Style\Font;
+
 /**
  * Rich text element interface.
  */
@@ -43,7 +45,7 @@ public function setText($pText = '');
     /**
      * Get font.
      *
-     * @return \PhpOffice\PhpPresentation\Style\Font
+     * @return Font
      */
     public function getFont();
 

tests/PhpPresentation/Tests/PhpPresentationTest.php

@@ -24,6 +24,7 @@
 use PhpOffice\PhpPresentation\Exception\OutOfBoundsException;
 use PhpOffice\PhpPresentation\PhpPresentation;
 use PhpOffice\PhpPresentation\PresentationProperties;
+use PhpOffice\PhpPresentation\Slide;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -43,7 +44,7 @@ public function testConstruct(): void
 
         self::assertEquals(new DocumentProperties(), $object->getDocumentProperties());
         self::assertEquals(new DocumentLayout(), $object->getLayout());
-        self::assertInstanceOf('PhpOffice\\PhpPresentation\\Slide', $object->getSlide());
+        self::assertInstanceOf(Slide::class, $object->getSlide());
         self::assertCount(1, $object->getAllSlides());
         self::assertEquals(0, $object->getIndex($slide));
         self::assertEquals(1, $object->getSlideCount());
@@ -129,4 +130,64 @@ public function testSetActiveSlideIndexException(): void
         $object = new PhpPresentation();
         $object->setActiveSlideIndex(1);
     }
+
+    public function testAddSlideAtStart(): void
+    {
+        $presentation = new PhpPresentation();
+        $presentation->removeSlideByIndex(0);
+        $slide1 = new Slide($presentation);
+        $slide1->setName('Slide 1');
+        $slide2 = new Slide($presentation);
+        $slide2->setName('Slide 2');
+        $slide3 = new Slide($presentation);
+        $slide3->setName('Slide 3');
+
+        $presentation->addSlide($slide1);
+        $presentation->addSlide($slide2);
+        $presentation->addSlide($slide3, 0);
+
+        self::assertEquals('Slide 3', $presentation->getSlide(0)->getName());
+        self::assertEquals('Slide 1', $presentation->getSlide(1)->getName());
+        self::assertEquals('Slide 2', $presentation->getSlide(2)->getName());
+    }
+
+    public function testAddSlideAtMiddle(): void
+    {
+        $presentation = new PhpPresentation();
+        $presentation->removeSlideByIndex(0);
+        $slide1 = new Slide($presentation);
+        $slide1->setName('Slide 1');
+        $slide2 = new Slide($presentation);
+        $slide2->setName('Slide 2');
+        $slide3 = new Slide($presentation);
+        $slide3->setName('Slide 3');
+
+        $presentation->addSlide($slide1);
+        $presentation->addSlide($slide2);
+        $presentation->addSlide($slide3, 1);
+
+        self::assertEquals('Slide 1', $presentation->getSlide(0)->getName());
+        self::assertEquals('Slide 3', $presentation->getSlide(1)->getName());
+        self::assertEquals('Slide 2', $presentation->getSlide(2)->getName());
+    }
+
+    public function testAddSlideAtEnd(): void
+    {
+        $presentation = new PhpPresentation();
+        $presentation->removeSlideByIndex(0);
+        $slide1 = new Slide($presentation);
+        $slide1->setName('Slide 1');
+        $slide2 = new Slide($presentation);
+        $slide2->setName('Slide 2');
+        $slide3 = new Slide($presentation);
+        $slide3->setName('Slide 3');
+
+        $presentation->addSlide($slide1);
+        $presentation->addSlide($slide2);
+        $presentation->addSlide($slide3);
+
+        self::assertEquals('Slide 1', $presentation->getSlide(0)->getName());
+        self::assertEquals('Slide 2', $presentation->getSlide(1)->getName());
+        self::assertEquals('Slide 3', $presentation->getSlide(2)->getName());
+    }
 }