3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM EntityTag records.
15 * Use this api to add/remove tags from a contact/activity/etc.
16 * To create/update/delete the tags themselves, use the Tag api.
18 * @package CiviCRM_APIv3
24 * @param array $params
28 function civicrm_api3_entity_tag_get($params) {
29 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
33 * Adjust Metadata for Get action.
35 * The metadata is used for setting defaults, documentation & validation.
37 * @param array $params
38 * Array of parameters determined by getfields.
40 function _civicrm_api3_entity_tag_get_spec(&$params) {
41 $params['entity_id']['api.aliases'] = ['contact_id'];
42 $params['entity_table']['api.default'] = 'civicrm_contact';
46 * Create an entity tag.
48 * @param array $params
52 function civicrm_api3_entity_tag_create($params) {
53 return _civicrm_api3_entity_tag_common($params, 'add');
57 * Mark entity tag as removed.
59 * @param array $params
63 function civicrm_api3_entity_tag_delete($params) {
65 return _civicrm_api3_entity_tag_common($params, 'remove');
71 * @param array $params
73 function _civicrm_api3_entity_tag_delete_spec(&$params) {
74 // set as not required as tag_id also acceptable & no either/or std yet
75 $params['id']['api.required'] = 0;
79 * Helper function for formatting tags (part of api v2 legacy).
81 * @param array $params
86 function _civicrm_api3_entity_tag_common($params, $op = 'add') {
88 $entityIDs = $tagIDs = [];
89 $entityTable = 'civicrm_contact';
90 if (is_array($params)) {
91 foreach ($params as $n => $v) {
92 if ((substr($n, 0, 10) == 'contact_id') ||
(substr($n, 0, 9) == 'entity_id')) {
95 elseif (substr($n, 0, 6) == 'tag_id') {
97 $tagIDs = array_merge($tagIDs, $v);
103 elseif (substr($n, 0, 12) == 'entity_table') {
109 if (empty($entityIDs)) {
110 return civicrm_api3_create_error('contact_id is a required field');
113 if (empty($tagIDs)) {
114 if ($op == 'remove') {
115 $tagIDs = array_keys(CRM_Core_BAO_EntityTag
::getContactTags($entityIDs[0]));
118 return civicrm_api3_create_error('tag_id is a required field');
122 $values = ['is_error' => 0];
124 $values['total_count'] = $values['added'] = $values['not_added'] = 0;
125 foreach ($tagIDs as $tagID) {
126 list($te, $a, $na) = CRM_Core_BAO_EntityTag
::addEntitiesToTag($entityIDs, $tagID, $entityTable,
127 CRM_Utils_Array
::value('check_permissions', $params));
128 $values['total_count'] +
= $te;
129 $values['added'] +
= $a;
130 $values['not_added'] +
= $na;
134 $values['total_count'] = $values['removed'] = $values['not_removed'] = 0;
135 foreach ($tagIDs as $tagID) {
136 list($te, $r, $nr) = CRM_Core_BAO_EntityTag
::removeEntitiesFromTag($entityIDs, $tagID, $entityTable, CRM_Utils_Array
::value('check_permissions', $params));
137 $values['total_count'] +
= $te;
138 $values['removed'] +
= $r;
139 $values['not_removed'] +
= $nr;
142 if (empty($values['added']) && empty($values['removed'])) {
143 $values['is_error'] = 1;
144 $values['error_message'] = "Unable to $op tags";
150 * Replace tags for an entity
152 function civicrm_api3_entity_tag_replace($params) {
153 $transaction = new CRM_Core_Transaction();
156 $baseParams = _civicrm_api3_generic_replace_base_params($params);
157 unset($baseParams['tag_id']);
159 // Lookup pre-existing records
160 $preexisting = civicrm_api3('entity_tag', 'get', $baseParams);
161 $preexisting = array_column($preexisting['values'], 'tag_id');
162 $toAdd = $params['tag_id'] ??
array_column($params['values'], 'tag_id');
163 $toRemove = array_diff($preexisting, $toAdd);
167 $result = _civicrm_api3_entity_tag_common(array_merge($baseParams, ['tag_id' => $toAdd]), 'add');
170 $result +
= _civicrm_api3_entity_tag_common(array_merge($baseParams, ['tag_id' => $toRemove]), 'remove');
173 unset($result['is_error'], $result['error_message']);
175 return civicrm_api3_create_success($result, $params, 'EntityTag', 'replace');
177 catch (Exception
$e) {
178 $transaction->rollback();
179 return civicrm_api3_create_error($e->getMessage());