Feature: add limit option to setvalues

docs/changes/1.x/1.3.0.md

@@ -45,5 +45,6 @@
 - Bump mpdf/mpdf from 8.2.2 to 8.2.4 by [@dependabot](https://github.com/dependabot) in [#2647](https://github.com/PHPOffice/PHPWord/pull/2647)
 - Bump phenx/php-svg-lib from 0.5.1 to 0.5.4 by [@dependabot](https://github.com/dependabot) in [#2649](https://github.com/PHPOffice/PHPWord/pull/2649)
 - Bump phpstan/phpstan-phpunit from 1.3.15 to 1.4.0 by [@dependabot](https://github.com/dependabot) in [#2648](https://github.com/PHPOffice/PHPWord/pull/2648)
+- Adding the possibility to use iterate search and replace with setValues by [@moghwan](https://github.com/moghwan) in [#2632](https://github.com/PHPOffice/PHPWord/pull/2640)
 
 ### BC Breaks

src/PhpWord/TemplateProcessor.php

@@ -362,10 +362,10 @@ public function setValue($search, $replace, $limit = self::MAXIMUM_REPLACEMENTS_
     /**
      * Set values from a one-dimensional array of "variable => value"-pairs.
      */
-    public function setValues(array $values): void
+    public function setValues(array $values, int $limit = self::MAXIMUM_REPLACEMENTS_DEFAULT): void
     {
         foreach ($values as $macro => $replace) {
-            $this->setValue($macro, $replace);
+            $this->setValue($macro, $replace, $limit);
         }
     }
 

tests/PhpWordTests/TemplateProcessorTest.php

@@ -614,12 +614,53 @@ public function testSetValues(): void
             <w:r>
                 <w:t xml:space="preserve">Hello ${firstname} ${lastname}</w:t>
             </w:r>
-        </w:p>';
+        </w:p>
+        <w:p>
+            <w:r>
+                <w:t xml:space="preserve">Hello ${firstname} ${lastname}</w:t>
+            </w:r>
+        </w:p>
+        <w:p>
+            <w:r>
+                <w:t xml:space="preserve">Hello ${firstname} ${lastname}</w:t>
+            </w:r>
+        </w:p>
+        ';
 
         $templateProcessor = new TestableTemplateProcesor($mainPart);
         $templateProcessor->setValues(['firstname' => 'John', 'lastname' => 'Doe']);
-
         self::assertStringContainsString('Hello John Doe', $templateProcessor->getMainPart());
+        self::assertStringNotContainsString('Hello ${firstname} ${lastname}', $templateProcessor->getMainPart());
+
+        // test with a specific limit that is lower than the number of replacements
+        $templateProcessor = new TestableTemplateProcesor($mainPart);
+        $templateProcessor->setValues(['firstname' => 'Jane', 'lastname' => 'Smith'], 2);
+        $variablesCounts = $templateProcessor->getVariableCount();
+
+        self::assertStringContainsString('Hello Jane Smith', $templateProcessor->getMainPart());
+        self::assertStringContainsString('Hello ${firstname} ${lastname}', $templateProcessor->getMainPart());
+        self::assertEquals(1, $variablesCounts['firstname']);
+        self::assertEquals(1, $variablesCounts['lastname']);
+
+        // test with a limit for only one replacement
+        $templateProcessor = new TestableTemplateProcesor($mainPart);
+        $templateProcessor->setValues(['firstname' => 'Alice', 'lastname' => 'Wonderland'], 1);
+        $variablesCounts = $templateProcessor->getVariableCount();
+
+        self::assertStringContainsString('Hello Alice Wonderland', $templateProcessor->getMainPart());
+        self::assertStringContainsString('Hello ${firstname} ${lastname}', $templateProcessor->getMainPart());
+        self::assertEquals(2, $variablesCounts['firstname']);
+        self::assertEquals(2, $variablesCounts['lastname']);
+
+        // Test with a limit of 0 for a result with no replacements
+        $templateProcessor = new TestableTemplateProcesor($mainPart);
+        $templateProcessor->setValues(['firstname' => 'Test', 'lastname' => 'User'], 0);
+        $variablesCounts = $templateProcessor->getVariableCount();
+
+        self::assertStringContainsString('Hello ${firstname} ${lastname}', $templateProcessor->getMainPart());
+        self::assertStringNotContainsString('Hello Test User', $templateProcessor->getMainPart());
+        self::assertEquals(3, $variablesCounts['firstname']);
+        self::assertEquals(3, $variablesCounts['lastname']);
     }
 
     /**