CRM/Utils/API/AbstractFieldCoder.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * Base class for writing API_Wrappers which generically manipulate the content
  14  * of all fields (except for some black-listed skip-fields).
  15  *
  16  * @package CRM
  17  * @copyright CiviCRM LLC https://civicrm.org/licensing
  18  */
  19
  20 require_once 'api/Wrapper.php';
  21
  22 /**
  23  * Class CRM_Utils_API_AbstractFieldCoder.
  24  */
  25 abstract class CRM_Utils_API_AbstractFieldCoder implements API_Wrapper {
  26
  27   /**
  28    * Get skipped fields.
  29    *
  30    * @return array<string>
  31    *   List of field names
  32    */
  33   public function getSkipFields() {
  34     return NULL;
  35   }
  36
  37   /**
  38    * Is field skipped.
  39    *
  40    * @param string $fldName
  41    *
  42    * @return bool
  43    *   TRUE if encoding should be skipped for this field
  44    */
  45   public function isSkippedField($fldName) {
  46     $skipFields = $this->getSkipFields();
  47     if ($skipFields === NULL) {
  48       return FALSE;
  49     }
  50     // Strip extra numbers from custom fields e.g. custom_32_1 should be custom_32
  51     if (strpos($fldName, 'custom_') === 0) {
  52       list($fldName, $customId) = explode('_', $fldName);
  53       $fldName .= '_' . $customId;
  54     }
  55
  56     // Field should be skipped
  57     if (in_array($fldName, $skipFields)) {
  58       return TRUE;
  59     }
  60     // Field is multilingual and after cutting off _xx_YY should be skipped (CRM-7230)…
  61     if ((preg_match('/_[a-z][a-z]_[A-Z][A-Z]$/', $fldName) && in_array(substr($fldName, 0, -6), $skipFields))) {
  62       return TRUE;
  63     }
  64     // Field can take multiple entries, eg. fieldName[1], fieldName[2], etc.
  65     // We remove the index and check again if the fieldName in the list of skipped fields.
  66     $matches = [];
  67     if (preg_match('/^(.*)\[\d+\]/', $fldName, $matches) && in_array($matches[1], $skipFields)) {
  68       return TRUE;
  69     }
  70
  71     return FALSE;
  72   }
  73
  74   /**
  75    * Going to filter the submitted values.
  76    *
  77    * @param array|string $values the field value from the API
  78    */
  79   abstract public function encodeInput(&$values);
  80
  81   /**
  82    * Decode output.
  83    *
  84    * @param string $values
  85    *
  86    * @return mixed
  87    */
  88   abstract public function decodeOutput(&$values);
  89
  90   /**
  91    * @inheritDoc
  92    */
  93   public function fromApiInput($apiRequest) {
  94     $lowerAction = strtolower($apiRequest['action']);
  95     if ($apiRequest['version'] == 3 && in_array($lowerAction, ['get', 'create'])) {
  96       // note: 'getsingle', 'replace', 'update', and chaining all build on top of 'get'/'create'
  97       foreach ($apiRequest['params'] as $key => $value) {
  98         // Don't apply escaping to API control parameters (e.g. 'api.foo' or 'options.foo')
  99         // and don't apply to other skippable fields
 100         if (!$this->isApiControlField($key) && !$this->isSkippedField($key)) {
 101           $this->encodeInput($apiRequest['params'][$key]);
 102         }
 103       }
 104     }
 105     elseif ($apiRequest['version'] == 3 && $lowerAction == 'setvalue') {
 106       if (isset($apiRequest['params']['field']) && isset($apiRequest['params']['value'])) {
 107         if (!$this->isSkippedField($apiRequest['params']['field'])) {
 108           $this->encodeInput($apiRequest['params']['value']);
 109         }
 110       }
 111     }
 112     return $apiRequest;
 113   }
 114
 115   /**
 116    * @inheritDoc
 117    */
 118   public function toApiOutput($apiRequest, $result) {
 119     $lowerAction = strtolower($apiRequest['action']);
 120     if ($apiRequest['version'] == 3 && in_array($lowerAction, ['get', 'create', 'setvalue', 'getquick'])) {
 121       foreach ($result as $key => $value) {
 122         // Don't apply escaping to API control parameters (e.g. 'api.foo' or 'options.foo')
 123         // and don't apply to other skippable fields
 124         if (!$this->isApiControlField($key) && !$this->isSkippedField($key)) {
 125           $this->decodeOutput($result[$key]);
 126         }
 127       }
 128     }
 129     // setvalue?
 130     return $result;
 131   }
 132
 133   /**
 134    * @param $key
 135    *
 136    * @return bool
 137    */
 138   protected function isApiControlField($key) {
 139     return (FALSE !== strpos($key, '.'));
 140   }
 141
 142 }