X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=Civi%2FToken%2FTokenRow.php;h=536b6ab237245674db3f83319a4b2ebd482e7e1d;hb=5b394c8f531cb30eccf5507bf7c08997603bf217;hp=883e29089a2ebf1360efd9bdf15c2760ce640219;hpb=a40e45577fc9cfc15558d1e6c0f242fbf900f5c3;p=civicrm-core.git

diff --git a/Civi/Token/TokenRow.php b/Civi/Token/TokenRow.php
index 883e29089a..536b6ab237 100644
--- a/Civi/Token/TokenRow.php
+++ b/Civi/Token/TokenRow.php
@@ -5,67 +5,106 @@ namespace Civi\Token;
  * Class TokenRow
  * @package Civi\Token
  *
- * A TokenRow is a helper providing simplified access to the
- * TokenProcessor.
+ * A TokenRow is a helper/stub providing simplified access to the TokenProcessor.
+ * There are two common cases for using the TokenRow stub:
  *
- * A TokenRow combines two elements:
- *   - context: This is backend data provided by the controller.
- *   - tokens: This is frontend data that can be mail-merged.
+ * (1) When setting up a job, you may specify general/baseline info.
+ * This is called the "context" data. Here, we create two rows:
  *
- * The context and tokens can be accessed using either methods
- * or attributes. The methods are appropriate for updates
- * (and generally accept a mix of arrays), and the attributes
- * are appropriate for reads.
+ * ```
+ * $proc->addRow()->context('contact_id', 123);
+ * $proc->addRow()->context('contact_id', 456);
+ * ```
  *
- * To update the context or the tokens, use the methods.
- * Note that the methods are fairly flexible about accepting
- * single values or arrays. If given an array, the values
- * will be merged recursively.
+ * (2) When defining a token (eg `{profile.viewUrl}`), you might read the
+ * context-data (`contact_id`) and set the token-data (`profile => viewUrl`):
  *
- * @code
- * $row
- *   ->context('contact_id', 123)
- *   ->context(array('contact_id' => 123))
- *   ->tokens('profile', array('viewUrl' => 'http://example.com'))
- *   ->tokens('profile', 'viewUrl, 'http://example.com');
+ * ```
+ * foreach ($proc->getRows() as $row) {
+ *   $row->tokens('profile', [
+ *     'viewUrl' => 'http://example.com/profile?cid=' . urlencode($row->context['contact_id'];
+ *   ]);
+ * }
+ * ```
  *
+ * The context and tokens can be accessed using either methods or attributes.
+ *
+ * ```
+ * # Setting context data
+ * $row->context('contact_id', 123);
+ * $row->context(['contact_id' => 123]);
+ *
+ * # Setting token data
+ * $row->tokens('profile', ['viewUrl' => 'http://example.com/profile?cid=123']);
+ * $row->tokens('profile', 'viewUrl, 'http://example.com/profile?cid=123');
+ *
+ * # Reading context data
  * echo $row->context['contact_id'];
+ *
+ * # Reading token data
  * echo $row->tokens['profile']['viewUrl'];
+ * ```
  *
- * $row->tokens('profile', array(
- *   'viewUrl' => 'http://example.com/view/' . urlencode($row->context['contact_id'];
- * ));
- * @endcode
+ * Note: The methods encourage a "fluent" style. They were written for PHP 5.3
+ * (eg before short-array syntax was supported) and are fairly flexible about
+ * input notations (e.g. `context(string $key, mixed $value)` vs `context(array $keyValuePairs)`).
+ *
+ * Note: An instance of `TokenRow` is a stub which only contains references to the
+ * main data in `TokenProcessor`. There may be several `TokenRow` stubs
+ * referencing the same `TokenProcessor`. You can think of `TokenRow` objects as
+ * lightweight and disposable.
  */
 class TokenRow {
 
   /**
+   * The token-processor is where most data is actually stored.
+   *
+   * Note: Not intended for public usage. However, this is marked public to allow
+   * interaction classes in this package (`TokenProcessor`<=>`TokenRow`<=>`TokenRowContext`).
+   *
    * @var TokenProcessor
    */
   public $tokenProcessor;
 
+  /**
+   * Row ID - the record within TokenProcessor that we're accessing.
+   *
+   * @var int
+   */
   public $tokenRow;
 
+  /**
+   * The MIME type associated with new token-values.
+   *
+   * This is generally manipulated as part of a fluent chain, eg
+   *
+   * $row->format('text/plain')->token(['display_name', 'Alice Bobdaughter']);
+   *
+   * @var string
+   */
   public $format;
 
   /**
    * @var array|\ArrayAccess
    *   List of token values.
-   *   Ex: array('contact' => array('display_name' => 'Alice')).
+   *   This is a facade for the TokenProcessor::$rowValues.
+   *   Ex: ['contact' => ['display_name' => 'Alice']]
    */
   public $tokens;
 
   /**
    * @var array|\ArrayAccess
    *   List of context values.
-   *   Ex: array('controller' => 'CRM_Foo_Bar').
+   *   This is a facade for the TokenProcessor::$rowContexts.
+   *   Ex: ['controller' => 'CRM_Foo_Bar']
    */
   public $context;
 
   public function __construct(TokenProcessor $tokenProcessor, $key) {
     $this->tokenProcessor = $tokenProcessor;
     $this->tokenRow = $key;
-    $this->format('text/plain'); // Set a default.
+    // Set a default.
+    $this->format('text/plain');
     $this->context = new TokenRowContext($tokenProcessor, $key);
   }
 
@@ -138,7 +177,7 @@ class TokenRow {
     $customFieldName = "custom_" . $customFieldID;
     $record = civicrm_api3($entity, "getSingle", [
       'return' => $customFieldName,
-       'id' => $entityID,
+      'id' => $entityID,
     ]);
     $fieldValue = \CRM_Utils_Array::value($customFieldName, $record, '');
 
@@ -156,7 +195,7 @@ class TokenRow {
    * @param string $tokenEntity
    * @param string $tokenField
    * @param string $baoName
-   * @param array $baoField
+   * @param string $baoField
    * @param mixed $fieldValue
    * @return TokenRow
    * @throws \CRM_Core_Exception
@@ -205,10 +244,10 @@ class TokenRow {
     }
 
     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/html'])) {
-      $this->tokenProcessor->rowValues[$this->tokenRow]['text/html'] = array();
+      $this->tokenProcessor->rowValues[$this->tokenRow]['text/html'] = [];
     }
     if (!isset($this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'])) {
-      $this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'] = array();
+      $this->tokenProcessor->rowValues[$this->tokenRow]['text/plain'] = [];
     }
 
     $htmlTokens = &$this->tokenProcessor->rowValues[$this->tokenRow]['text/html'];
@@ -218,7 +257,7 @@ class TokenRow {
       case 'text/html':
         // Plain => HTML.
         foreach ($textTokens as $entity => $values) {
-          $entityFields = civicrm_api3($entity, "getFields", array('api_action' => 'get'));
+          $entityFields = civicrm_api3($entity, "getFields", ['api_action' => 'get']);
           foreach ($values as $field => $value) {
             if (!isset($htmlTokens[$entity][$field])) {
               // CRM-18420 - Activity Details Field are enclosed within <p>,
@@ -305,8 +344,7 @@ class TokenRowContext implements \ArrayAccess, \IteratorAggregate, \Countable {
    * @return bool
    */
   public function offsetExists($offset) {
-    return
-      isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])
+    return isset($this->tokenProcessor->rowContexts[$this->tokenRow][$offset])
       || isset($this->tokenProcessor->context[$offset]);
   }