CRM/Utils/API/MatchOption.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2018                                |
   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  * Implement the "match" and "match-mandatory" options. If the submitted record doesn't have an ID
  30  * but a "match" key is specified, then we will automatically search for pre-existing record and
  31  * fill-in the missing ID. The "match" or "match-mandatory" can specified as a string (the name of the key
  32  * to match on) or array (the names of several keys to match on).
  33  *
  34  * Note that "match" and "match-mandatory" behave the same in the case where one matching record
  35  * exists (ie they update the record). They also behave the same if there are multiple matching
  36  * records (ie they throw an error).  However, if there is no matching record, they differ:
  37  *   - "match-mandatory" will generate an error
  38  *   - "match" will allow action to proceed -- thus inserting a new record
  39  *
  40  * @code
  41  * $result = civicrm_api('contact', 'create', array(
  42  *   'options' => array(
  43  *     'match' => array('last_name', 'first_name')
  44  *   ),
  45  *   'first_name' => 'Jeffrey',
  46  *   'last_name' => 'Lebowski',
  47  *   'nick_name' => 'The Dude',
  48  * ));
  49  * @endcode
  50  *
  51  * @package CRM
  52  * @copyright CiviCRM LLC (c) 2004-2018
  53  */
  54
  55 require_once 'api/Wrapper.php';
  56
  57 /**
  58  * Class CRM_Utils_API_MatchOption
  59  */
  60 class CRM_Utils_API_MatchOption implements API_Wrapper {
  61
  62   /**
  63    * @var CRM_Utils_API_MatchOption
  64    */
  65   private static $_singleton = NULL;
  66
  67   /**
  68    * Singleton function.
  69    *
  70    * @return CRM_Utils_API_MatchOption
  71    */
  72   public static function singleton() {
  73     if (self::$_singleton === NULL) {
  74       self::$_singleton = new CRM_Utils_API_MatchOption();
  75     }
  76     return self::$_singleton;
  77   }
  78
  79   /**
  80    * @inheritDoc
  81    */
  82   public function fromApiInput($apiRequest) {
  83
  84     // Parse options.match or options.match-mandatory
  85     $keys = NULL;
  86     if (isset($apiRequest['params'], $apiRequest['params']['options']) && is_array($apiRequest['params']['options'])) {
  87       if (isset($apiRequest['params']['options']['match-mandatory'])) {
  88         $isMandatory = TRUE;
  89         $keys = $apiRequest['params']['options']['match-mandatory'];
  90       }
  91       elseif (isset($apiRequest['params']['options']['match'])) {
  92         $isMandatory = FALSE;
  93         $keys = $apiRequest['params']['options']['match'];
  94       }
  95       if (is_string($keys)) {
  96         $keys = array($keys);
  97       }
  98     }
  99
 100     // If one of the options was specified, then try to match records.
 101     // Matching logic differs for 'create' and 'replace' actions.
 102     if ($keys !== NULL) {
 103       switch ($apiRequest['action']) {
 104         case 'create':
 105           if (empty($apiRequest['params']['id'])) {
 106             $apiRequest['params'] = $this->match($apiRequest['entity'], $apiRequest['params'], $keys, $isMandatory);
 107           }
 108           break;
 109
 110         case 'replace':
 111           // In addition to matching on the listed keys, also match on the set-definition keys.
 112           // For example, if the $apiRequest is to "replace the set of civicrm_emails for contact_id=123 while
 113           // matching emails on location_type_id", then we would need to search for pre-existing emails using
 114           // both 'contact_id' and 'location_type_id'
 115           $baseParams = _civicrm_api3_generic_replace_base_params($apiRequest['params']);
 116           $keys = array_unique(array_merge(
 117             array_keys($baseParams),
 118             $keys
 119           ));
 120
 121           // attempt to match each replacement item
 122           foreach ($apiRequest['params']['values'] as $offset => $createParams) {
 123             $createParams = array_merge($baseParams, $createParams);
 124             $createParams = $this->match($apiRequest['entity'], $createParams, $keys, $isMandatory);
 125             $apiRequest['params']['values'][$offset] = $createParams;
 126           }
 127           break;
 128
 129         default:
 130           // be forgiving of sloppy api calls
 131       }
 132     }
 133
 134     return $apiRequest;
 135   }
 136
 137   /**
 138    * Attempt to match a contact. This filters/updates the $createParams if there is a match.
 139    *
 140    * @param string $entity
 141    * @param array $createParams
 142    * @param array $keys
 143    * @param bool $isMandatory
 144    *
 145    * @return array
 146    *   revised $createParams, including 'id' if known
 147    * @throws API_Exception
 148    */
 149   public function match($entity, $createParams, $keys, $isMandatory) {
 150     $getParams = $this->createGetParams($createParams, $keys);
 151     $getResult = civicrm_api3($entity, 'get', $getParams);
 152     if ($getResult['count'] == 0) {
 153       if ($isMandatory) {
 154         throw new API_Exception("Failed to match existing record");
 155       }
 156       return $createParams; // OK, don't care
 157     }
 158     elseif ($getResult['count'] == 1) {
 159       $item = array_shift($getResult['values']);
 160       $createParams['id'] = $item['id'];
 161       return $createParams;
 162     }
 163     else {
 164       throw new API_Exception("Ambiguous match criteria");
 165     }
 166   }
 167
 168   /**
 169    * @inheritDoc
 170    */
 171   public function toApiOutput($apiRequest, $result) {
 172     return $result;
 173   }
 174
 175   /**
 176    * Create APIv3 "get" parameters to lookup an existing record using $keys
 177    *
 178    * @param array $origParams
 179    *   Api request.
 180    * @param array $keys
 181    *   List of keys to match against.
 182    *
 183    * @return array
 184    *   APIv3 $params
 185    */
 186   public function createGetParams($origParams, $keys) {
 187     $params = array('version' => 3);
 188     foreach ($keys as $key) {
 189       $params[$key] = CRM_Utils_Array::value($key, $origParams, '');
 190     }
 191     return $params;
 192   }
 193
 194 }