Commit | Line | Data |
---|---|---|
c8463688 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
06b69b18 | 4 | | CiviCRM version 4.5 | |
c8463688 | 5 | +--------------------------------------------------------------------+ |
06b69b18 | 6 | | Copyright CiviCRM LLC (c) 2004-2014 | |
c8463688 TO |
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 | |
e4b4e33a TO |
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). | |
c8463688 TO |
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 | |
06b69b18 | 52 | * @copyright CiviCRM LLC (c) 2004-2014 |
c8463688 TO |
53 | * $Id$ |
54 | */ | |
55 | ||
56 | require_once 'api/Wrapper.php'; | |
57 | class CRM_Utils_API_MatchOption implements API_Wrapper { | |
58 | ||
59 | /** | |
60 | * @var CRM_Utils_API_MatchOption | |
61 | */ | |
62 | private static $_singleton = NULL; | |
63 | ||
64 | /** | |
65 | * @return CRM_Utils_API_MatchOption | |
66 | */ | |
67 | public static function singleton() { | |
68 | if (self::$_singleton === NULL) { | |
69 | self::$_singleton = new CRM_Utils_API_MatchOption(); | |
70 | } | |
71 | return self::$_singleton; | |
72 | } | |
73 | ||
74 | /** | |
75 | * {@inheritDoc} | |
76 | */ | |
77 | public function fromApiInput($apiRequest) { | |
e4b4e33a TO |
78 | // Parse options.match or options.match-mandatory |
79 | $keys = NULL; // array of fields to match against | |
80 | if (isset($apiRequest['params'], $apiRequest['params']['options'])) { | |
c8463688 TO |
81 | if (isset($apiRequest['params']['options']['match-mandatory'])) { |
82 | $isMandatory = TRUE; | |
83 | $keys = $apiRequest['params']['options']['match-mandatory']; | |
84 | } | |
e4b4e33a | 85 | elseif (isset($apiRequest['params']['options']['match'])) { |
c8463688 TO |
86 | $isMandatory = FALSE; |
87 | $keys = $apiRequest['params']['options']['match']; | |
88 | } | |
e4b4e33a TO |
89 | if (is_string($keys)) { |
90 | $keys = array($keys); | |
91 | } | |
92 | } | |
c8463688 | 93 | |
e4b4e33a TO |
94 | // If one of the options was specified, then try to match records. |
95 | // Matching logic differs for 'create' and 'replace' actions. | |
96 | if ($keys !== NULL) { | |
97 | switch($apiRequest['action']) { | |
98 | case 'create': | |
99 | if (empty($apiRequest['params']['id'])) { | |
100 | $apiRequest['params'] = $this->match($apiRequest['entity'], $apiRequest['params'], $keys, $isMandatory); | |
101 | } | |
102 | break; | |
103 | case 'replace': | |
104 | // In addition to matching on the listed keys, also match on the set-definition keys. | |
105 | // For example, if the $apiRequest is to "replace the set of civicrm_emails for contact_id=123 while | |
106 | // matching emails on location_type_id", then we would need to search for pre-existing emails using | |
107 | // both 'contact_id' and 'location_type_id' | |
108 | $baseParams = _civicrm_api3_generic_replace_base_params($apiRequest['params']); | |
109 | $keys = array_unique(array_merge( | |
110 | array_keys($baseParams), | |
111 | $keys | |
112 | )); | |
113 | ||
114 | // attempt to match each replacement item | |
115 | foreach($apiRequest['params']['values'] as $offset => $createParams) { | |
116 | $createParams = array_merge($baseParams, $createParams); | |
117 | $createParams = $this->match($apiRequest['entity'], $createParams, $keys, $isMandatory); | |
118 | $apiRequest['params']['values'][$offset] = $createParams; | |
119 | } | |
120 | break; | |
121 | default: | |
122 | // be forgiveful of sloppily api calls | |
c8463688 TO |
123 | } |
124 | } | |
e4b4e33a | 125 | |
c8463688 TO |
126 | return $apiRequest; |
127 | } | |
128 | ||
e4b4e33a TO |
129 | /** |
130 | * Attempt to match a contact. This filters/updates the $createParams if there is a match. | |
131 | * | |
132 | * @param string $entity | |
133 | * @param array $createParams | |
134 | * @param array $keys | |
135 | * @param bool $isMandatory | |
136 | * @return array revised $createParams, including 'id' if known | |
137 | * @throws API_Exception | |
138 | */ | |
139 | public function match($entity, $createParams, $keys, $isMandatory) { | |
140 | $getParams = $this->createGetParams($createParams, $keys); | |
141 | $getResult = civicrm_api3($entity, 'get', $getParams); | |
142 | if ($getResult['count'] == 0) { | |
143 | if ($isMandatory) { | |
144 | throw new API_Exception("Failed to match existing record"); | |
145 | } | |
146 | return $createParams; // OK, don't care | |
147 | } | |
148 | elseif ($getResult['count'] == 1) { | |
149 | $item = array_shift($getResult['values']); | |
150 | $createParams['id'] = $item['id']; | |
151 | return $createParams; | |
152 | } | |
153 | else { | |
154 | throw new API_Exception("Ambiguous match criteria"); | |
155 | } | |
156 | } | |
157 | ||
c8463688 TO |
158 | /** |
159 | * {@inheritDoc} | |
160 | */ | |
161 | public function toApiOutput($apiRequest, $result) { | |
162 | return $result; | |
163 | } | |
164 | ||
165 | /** | |
166 | * Create APIv3 "get" parameters to lookup an existing record using $keys | |
167 | * | |
168 | * @param array $apiRequest | |
169 | * @param array $keys list of keys to match against | |
170 | * @return array APIv3 $params | |
171 | */ | |
e4b4e33a | 172 | function createGetParams($origParams, $keys) { |
c8463688 TO |
173 | $params = array('version' => 3); |
174 | foreach ($keys as $key) { | |
e4b4e33a | 175 | $params[$key] = CRM_Utils_Array::value($key, $origParams, ''); |
c8463688 TO |
176 | } |
177 | return $params; | |
178 | } | |
179 | } |