From 3faff3fcb0c52edb6041f1d4dba9f97883c95565 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Mon, 4 May 2020 22:54:38 -0700
Subject: [PATCH] (REF) TokenProcessor - Allowing adding rows by array

Before
-------------------

When composing a message, you need to add a row and then use the fluent
`TokenRow` stub, eg:

```php
$p->addRow()->context(['contact_id' => 123]);
$p->addRow()->context(['contact_id' => 456]);
```

After
-------------------

When composing a message, you don't have to use the fluent `TokenRow` stub.
Just give an array:

```php
$p->addRow(['contact_id' => 123]);
$p->addRow(['contact_id' => 456]);
```

Or:

```php
$p->addRows([
  ['contact_id' => 123],
  ['contact_id' => 456],
]);
```

You still have the option of using the fluent interface.
---
 Civi/Token/TokenProcessor.php                 | 29 +++++++++++++-
 .../phpunit/Civi/Token/TokenProcessorTest.php | 39 +++++++++++++++++++
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/Civi/Token/TokenProcessor.php b/Civi/Token/TokenProcessor.php
index 4fa03b9038..a2d74203e7 100644
--- a/Civi/Token/TokenProcessor.php
+++ b/Civi/Token/TokenProcessor.php
@@ -115,9 +115,12 @@ class TokenProcessor {
   /**
    * Add a row of data.
    *
+   * @param array|NULL $context
+   *   Optionally, initialize the context for this row.
+   *   Ex: ['contact_id' => 123].
    * @return TokenRow
    */
-  public function addRow() {
+  public function addRow($context = NULL) {
     $key = $this->next++;
     $this->rowContexts[$key] = [];
     $this->rowValues[$key] = [
@@ -125,7 +128,29 @@ class TokenProcessor {
       'text/html' => [],
     ];
 
-    return new TokenRow($this, $key);
+    $row = new TokenRow($this, $key);
+    if ($context !== NULL) {
+      $row->context($context);
+    }
+    return $row;
+  }
+
+  /**
+   * Add several rows.
+   *
+   * @param array $contexts
+   *   List of rows to add.
+   *   Ex: [['contact_id'=>123], ['contact_id'=>456]]
+   * @return TokenRow[]
+   *   List of row objects
+   */
+  public function addRows($contexts) {
+    $rows = [];
+    foreach ($contexts as $context) {
+      $row = $this->addRow($context);
+      $rows[$row->tokenRow] = $row;
+    }
+    return $rows;
   }
 
   /**
diff --git a/tests/phpunit/Civi/Token/TokenProcessorTest.php b/tests/phpunit/Civi/Token/TokenProcessorTest.php
index faf1e71943..bbef30cfe2 100644
--- a/tests/phpunit/Civi/Token/TokenProcessorTest.php
+++ b/tests/phpunit/Civi/Token/TokenProcessorTest.php
@@ -30,6 +30,45 @@ class TokenProcessorTest extends \CiviUnitTestCase {
     ];
   }
 
+  /**
+   * Test that a row can be added via "addRow(array $context)".
+   */
+  public function testAddRow() {
+    $p = new TokenProcessor($this->dispatcher, [
+      'controller' => __CLASS__,
+    ]);
+    $createdRow = $p->addRow(['one' => 'Apple'])
+      ->context('two', 'Banana');
+    $gotRow = $p->getRow(0);
+    foreach ([$createdRow, $gotRow] as $row) {
+      $this->assertEquals('Apple', $row->context['one']);
+      $this->assertEquals('Banana', $row->context['two']);
+    }
+  }
+
+  /**
+   * Test that multiple rows can be added via "addRows(array $contexts)".
+   */
+  public function testAddRows() {
+    $p = new TokenProcessor($this->dispatcher, [
+      'controller' => __CLASS__,
+    ]);
+    $createdRows = $p->addRows([
+      ['one' => 'Apple', 'two' => 'Banana'],
+      ['one' => 'Pomme', 'two' => 'Banane'],
+    ]);
+    $gotRow0 = $p->getRow(0);
+    foreach ([$createdRows[0], $gotRow0] as $row) {
+      $this->assertEquals('Apple', $row->context['one']);
+      $this->assertEquals('Banana', $row->context['two']);
+    }
+    $gotRow1 = $p->getRow(1);
+    foreach ([$createdRows[1], $gotRow1] as $row) {
+      $this->assertEquals('Pomme', $row->context['one']);
+      $this->assertEquals('Banane', $row->context['two']);
+    }
+  }
+
   /**
    * Check that the TokenRow helper can correctly read/update context
    * values.
-- 
2.25.1