CRM/Utils/API/AbstractFieldCoder.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.4                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * Base class for writing API_Wrappers which generically manipulate the content
  30  * of all fields (except for some black-listed skip-fields).
  31  *
  32  * @package CRM
  33  * @copyright CiviCRM LLC (c) 2004-2013
  34  * $Id$
  35  *
  36  */
  37
  38 require_once 'api/Wrapper.php';
  39 abstract class CRM_Utils_API_AbstractFieldCoder implements API_Wrapper {
  40
  41   /**
  42    * @return array<string> list of field names
  43    */
  44   public function getSkipFields() {
  45     return NULL;
  46   }
  47
  48   /**
  49    * @param string $fldName
  50    * @return bool TRUE if encoding should be skipped for this field
  51    */
  52   public function isSkippedField($fldName) {
  53     $skipFields = $this->getSkipFields();
  54     if ($skipFields === NULL) {
  55       return FALSE;
  56     }
  57
  58     // Field should be skipped
  59     if (in_array($fldName, $skipFields)) {
  60       return TRUE;
  61     }
  62     // Field is multilingual and after cutting off _xx_YY should be skipped (CRM-7230)…
  63     if ((preg_match('/_[a-z][a-z]_[A-Z][A-Z]$/', $fldName) && in_array(substr($fldName, 0, -6), $skipFields))) {
  64       return TRUE;
  65     }
  66     // Field can take multiple entries, eg. fieldName[1], fieldName[2], etc.
  67     // We remove the index and check again if the fieldName in the list of skipped fields.
  68     $matches = array();
  69     if (preg_match('/^(.*)\[\d+\]/', $fldName, $matches) && in_array($matches[1], $skipFields)) {
  70       return TRUE;
  71     }
  72
  73     return FALSE;
  74   }
  75
  76   /**
  77    * This function is going to filter the
  78    * submitted values.
  79    *
  80    * @param array|string $values the field value from the API
  81    */
  82   public abstract function encodeInput(&$values);
  83
  84   public abstract function decodeOutput(&$values);
  85
  86   /**
  87    * {@inheritDoc}
  88    */
  89   public function fromApiInput($apiRequest) {
  90     $lowerAction = strtolower($apiRequest['action']);
  91     if ($apiRequest['version'] == 3 && in_array($lowerAction, array('get', 'create'))) {
  92       // note: 'getsingle', 'replace', 'update', and chaining all build on top of 'get'/'create'
  93       foreach ($apiRequest['params'] as $key => $value) {
  94         // Don't apply escaping to API control parameters (e.g. 'api.foo' or 'options.foo')
  95         // and don't apply to other skippable fields
  96         if (!$this->isApiControlField($key) && !$this->isSkippedField($key)) {
  97           $this->encodeInput($apiRequest['params'][$key]);
  98         }
  99       }
 100     }
 101     elseif ($apiRequest['version'] == 3 && $lowerAction == 'setvalue') {
 102       if (isset($apiRequest['params']['field']) && isset($apiRequest['params']['value'])) {
 103         if (!$this->isSkippedField($apiRequest['params']['field'])) {
 104           $this->encodeInput($apiRequest['params']['value']);
 105         }
 106       }
 107     }
 108     return $apiRequest;
 109   }
 110
 111   /**
 112    * {@inheritDoc}
 113    */
 114   public function toApiOutput($apiRequest, $result) {
 115     $lowerAction = strtolower($apiRequest['action']);
 116     if ($apiRequest['version'] == 3 && in_array($lowerAction, array('get', 'create', 'setvalue'))) {
 117       foreach ($result as $key => $value) {
 118         // Don't apply escaping to API control parameters (e.g. 'api.foo' or 'options.foo')
 119         // and don't apply to other skippable fields
 120         if (!$this->isApiControlField($key) && !$this->isSkippedField($key)) {
 121           $this->decodeOutput($result[$key]);
 122         }
 123       }
 124     }
 125     // setvalue?
 126     return $result;
 127   }
 128
 129   /**
 130    * @return bool
 131    */
 132   protected function isApiControlField($key) {
 133     return (FALSE !== strpos($key, '.'));
 134   }
 135 }