Merge pull request #23488 from colemanw/afformGetHook
[civicrm-core.git] / api / v3 / Membership.php
CommitLineData
6a488035 1<?php
6a488035
TO
2/*
3 +--------------------------------------------------------------------+
a30c801b 4 | Copyright CiviCRM LLC. All rights reserved. |
6a488035 5 | |
a30c801b
TO
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 |
6a488035
TO
9 +--------------------------------------------------------------------+
10 */
11
12/**
13 *
244bbdd8 14 * This api exposes CiviCRM membership contact records.
6a488035
TO
15 *
16 * @package CiviCRM_APIv3
6a488035
TO
17 */
18
ed4cc29d
JT
19/**
20 * Adjust Metadata for Delete action.
21 *
22 * The metadata is used for setting defaults, documentation & validation.
23 *
24 * @param array $params
25 * Array of parameters determined by getfields.
26 */
27function _civicrm_api3_membership_delete_spec(&$params) {
cf8f0fff 28 $params['preserve_contribution'] = [
9a47d762
JT
29 'api.required' => 0,
30 'title' => 'Preserve Contribution',
31 'description' => 'By default this is 0, or 0 if not set. Set to 1 to preserve the associated contribution record when membership is deleted.',
32 'type' => CRM_Utils_Type::T_BOOLEAN,
cf8f0fff 33 ];
ed4cc29d
JT
34}
35
6a488035 36/**
244bbdd8 37 * Deletes an existing contact Membership.
6a488035 38 *
16b10e64 39 * @param array $params
cf470720 40 * Array array holding id - Id of the contact membership to be deleted.
8089541a 41 * @return array API result array.
8089541a 42 * @throws API_Exception
6a488035
TO
43 */
44function civicrm_api3_membership_delete($params) {
bbdc6c8b 45 if (isset($params['preserve_contribution'])) {
ed4cc29d
JT
46 if (CRM_Member_BAO_Membership::del($params['id'], $params['preserve_contribution'])) {
47 return civicrm_api3_create_success(TRUE, $params);
48 }
49 else {
77043bee 50 throw new API_Exception(ts('Could not delete membership'));
ed4cc29d
JT
51 }
52 }
53 else {
54 return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
55 }
6a488035
TO
56}
57
6a488035 58/**
dc64d047 59 * Create a Contact Membership.
6a488035
TO
60 *
61 * This API is used for creating a Membership for a contact.
62 * Required parameters : membership_type_id and status_id.
63 *
cf470720 64 * @param array $params
1747ab99 65 * Array of name/value property values of civicrm_membership.
6a488035 66 *
a6c01b45 67 * @return array
1747ab99 68 * API result array.
def3192c 69 *
70 * @throws \CRM_Core_Exception
71 * @throws \CiviCRM_API3_Exception
6a488035
TO
72 */
73function civicrm_api3_membership_create($params) {
6a488035 74 // check params for membership id during update
4d63cfde 75 if (!empty($params['id']) && !isset($params['skipStatusCal'])) {
5e4f7f74
EM
76 // Don't calculate status on existing membership - expect API use to pass them in
77 // or leave unchanged.
6a488035
TO
78 $params['skipStatusCal'] = 1;
79 }
80 else {
81 // also check for status id if override is set (during add/update)
4d63cfde 82 if (!empty($params['is_override']) && empty($params['status_id'])) {
6a488035
TO
83 return civicrm_api3_create_error('Status ID required');
84 }
85 }
86
cf8f0fff 87 $values = [];
6a488035
TO
88 _civicrm_api3_custom_format_params($params, $values, 'Membership');
89 $params = array_merge($params, $values);
90
fd88af0b 91 // Calculate membership dates
8f3aca71 92 // Fixme: This code belongs in the BAO
8147b703 93 if (empty($params['id']) || !empty($params['num_terms'])) {
fd88af0b 94 // If this is a new membership or we have a specified number of terms calculate membership dates.
8147b703
EM
95 if (empty($params['id'])) {
96 // This is a new membership, calculate the membership dates.
97 $calcDates = CRM_Member_BAO_MembershipType::getDatesForMembershipType(
98 $params['membership_type_id'],
99 CRM_Utils_Array::value('join_date', $params),
100 CRM_Utils_Array::value('start_date', $params),
101 CRM_Utils_Array::value('end_date', $params),
102 CRM_Utils_Array::value('num_terms', $params, 1)
103 );
104 }
105 else {
fd88af0b 106 // This is an existing membership, calculate the membership dates after renewal
7365dd7f
AP
107 // num_terms is treated as a 'special sauce' for is_renewal but this
108 // isn't really helpful for completing pendings.
8f3aca71
CW
109 $calcDates = CRM_Member_BAO_MembershipType::getRenewalDatesForMembershipType(
110 $params['id'],
111 NULL,
112 CRM_Utils_Array::value('membership_type_id', $params),
113 $params['num_terms']
114 );
8147b703
EM
115 }
116 foreach (['join_date', 'start_date', 'end_date'] as $date) {
117 if (empty($params[$date]) && isset($calcDates[$date])) {
118 $params[$date] = $calcDates[$date];
8f3aca71
CW
119 }
120 }
121 }
122
123 // Fixme: This code belongs in the BAO
f57cb50c 124 $ids = [];
fd88af0b
MW
125 if (empty($params['id'])) {
126 $params['action'] = CRM_Core_Action::ADD;
7c550ca0 127 }
fd88af0b
MW
128 else {
129 // edit mode
130 $params['action'] = CRM_Core_Action::UPDATE;
f57cb50c 131 // @todo remove $ids['membership'] is required in CRM_Price_BAO_LineItem::processPriceSet
4d63cfde 132 $ids['membership'] = $params['id'];
6a488035 133 }
6a488035 134
f57cb50c 135 // @todo stop passing $ids (membership and userId may be set above)
def3192c 136 $membershipBAO = CRM_Member_BAO_Membership::create($params, $ids);
6a488035 137
770d8a40 138 if (property_exists($membershipBAO, 'is_error')) {
6a488035
TO
139 // In case of no valid status for given dates, $membershipBAO
140 // is going to contain 'is_error' => "Error Message"
141 return civicrm_api3_create_error(ts('The membership can not be saved, no valid membership status for given dates'));
142 }
143
cf8f0fff 144 $membership = [];
6a488035
TO
145 _civicrm_api3_object_to_array($membershipBAO, $membership[$membershipBAO->id]);
146
244bbdd8 147 return civicrm_api3_create_success($membership, $params, 'Membership', 'create', $membershipBAO);
6a488035
TO
148
149}
11e09c59
TO
150
151/**
0aa0303c
EM
152 * Adjust Metadata for Create action.
153 *
154 * The metadata is used for setting defaults, documentation & validation.
6a488035 155 *
cf470720 156 * @param array $params
b081365f 157 * Array of parameters determined by getfields.
6a488035
TO
158 */
159function _civicrm_api3_membership_create_spec(&$params) {
160 $params['contact_id']['api.required'] = 1;
4d63cfde 161 $params['membership_type_id']['api.required'] = 1;
8f3aca71 162 $params['is_test']['api.default'] = 0;
cf8f0fff
CW
163 $params['membership_type_id']['api.aliases'] = ['membership_type'];
164 $params['status_id']['api.aliases'] = ['membership_status'];
165 $params['skipStatusCal'] = [
b2ed8e73
CW
166 'title' => 'Skip status calculation',
167 'description' => 'By default this is 0 if id is not set and 1 if it is set.',
d142432b 168 'type' => CRM_Utils_Type::T_BOOLEAN,
cf8f0fff
CW
169 ];
170 $params['num_terms'] = [
b2ed8e73
CW
171 'title' => 'Number of terms',
172 'description' => 'Terms to add/renew. If this parameter is passed, dates will be calculated automatically. If no id is passed (new membership) and no dates are given, num_terms will be assumed to be 1.',
68115618 173 'type' => CRM_Utils_Type::T_INT,
cf8f0fff 174 ];
6a488035 175}
5e4f7f74 176
4d63cfde 177/**
dc64d047 178 * Adjust Metadata for Get action.
4d63cfde 179 *
0aa0303c
EM
180 * The metadata is used for setting defaults, documentation & validation.
181 *
cf470720 182 * @param array $params
b081365f 183 * Array of parameters determined by getfields.
4d63cfde
CW
184 */
185function _civicrm_api3_membership_get_spec(&$params) {
cf8f0fff
CW
186 $params['membership_type_id']['api.aliases'] = ['membership_type'];
187 $params['active_only'] = [
b2ed8e73
CW
188 'title' => 'Active Only',
189 'description' => 'Only retrieve active memberships',
5e4f7f74 190 'type' => CRM_Utils_Type::T_BOOLEAN,
cf8f0fff 191 ];
4d63cfde
CW
192}
193
6a488035 194/**
244bbdd8 195 * Get contact Membership record.
6a488035
TO
196 *
197 * This api will return the membership records for the contacts
198 * having membership based on the relationship with the direct members.
199 *
2241036a 200 * @param array $params
cf470720 201 * Key/value pairs for contact_id and some.
6a488035
TO
202 * options affecting the desired results; has legacy support
203 * for just passing the contact_id itself as the argument
204 *
16b10e64
CW
205 * @return array
206 * Array of all found membership property values.
6a488035
TO
207 */
208function civicrm_api3_membership_get($params) {
4d63cfde 209 $activeOnly = $membershipTypeId = $membershipType = NULL;
6a488035 210
f748c073 211 $contactID = $params['contact_id'] ?? NULL;
a73daeff
E
212 if (!empty($params['filters']) && is_array($params['filters']) && isset($params['filters']['is_current'])) {
213 $activeOnly = $params['filters']['is_current'];
214 unset($params['filters']['is_current']);
6a488035
TO
215 }
216 $activeOnly = CRM_Utils_Array::value('active_only', $params, $activeOnly);
d031c654 217 if ($activeOnly && empty($params['status_id'])) {
cf8f0fff 218 $params['status_id'] = ['IN' => CRM_Member_BAO_MembershipStatus::getMembershipStatusCurrent()];
324116ad
SD
219 }
220
244bbdd8 221 $options = _civicrm_api3_get_options_from_params($params, TRUE, 'Membership', 'get');
d031c654 222 if ($options['is_count']) {
a73daeff 223 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
6a488035 224 }
9af2925b 225 $membershipValues = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, FALSE, 'Membership');
6a488035 226
37eda84b 227 $return = $options['return'];
22e263ad 228 if (empty($membershipValues) ||
37eda84b 229 (!empty($return)
230 && !array_key_exists('related_contact_id', $return)
231 && !array_key_exists('relationship_name', $return)
232 )
233 ) {
244bbdd8 234 return civicrm_api3_create_success($membershipValues, $params, 'Membership', 'get');
6a488035
TO
235 }
236
7c550ca0 237 $members = _civicrm_api3_membership_relationsship_get_customv2behaviour($params, $membershipValues, $contactID);
244bbdd8 238 return civicrm_api3_create_success($members, $params, 'Membership', 'get');
37eda84b 239}
240
37eda84b 241/**
1747ab99 242 * Non-standard behaviour inherited from v2.
46332f2b 243 *
cf470720
TO
244 * @param array $params
245 * Parameters passed into get function.
2884d956 246 * @param array $membershipValues
100fef9d 247 * @param int $contactID
46332f2b 248 *
a6c01b45 249 * @return array
72b3a70c 250 * result for calling function
46332f2b 251 */
37eda84b 252function _civicrm_api3_membership_relationsship_get_customv2behaviour(&$params, $membershipValues, $contactID) {
cf8f0fff 253 $relationships = [];
6a488035
TO
254 foreach ($membershipValues as $membershipId => $values) {
255 // populate the membership type name for the membership type id
e7f70535 256 $membershipType = CRM_Member_BAO_MembershipType::getMembershipTypeDetails($values['membership_type_id']) ?? [];
6a488035 257
e7f70535
SL
258 if (!empty($membershipType)) {
259 $membershipValues[$membershipId]['membership_name'] = $membershipType['name'];
6a488035 260
e7f70535
SL
261 if (!empty($membershipType['relationship_type_id'])) {
262 $relationships[$membershipType['relationship_type_id']] = $membershipId;
263 }
6a488035
TO
264 }
265
266 // populating relationship type name.
267 $relationshipType = new CRM_Contact_BAO_RelationshipType();
f748c073 268 $relationshipType->id = $membershipType['relationship_type_id'] ?? NULL;
6a488035
TO
269 if ($relationshipType->find(TRUE)) {
270 $membershipValues[$membershipId]['relationship_name'] = $relationshipType->name_a_b;
271 }
272
e9ff5391 273 _civicrm_api3_custom_data_get($membershipValues[$membershipId], CRM_Utils_Array::value('check_permissions', $params), 'Membership', $membershipId, NULL, $values['membership_type_id']);
6a488035
TO
274 }
275
276 $members = $membershipValues;
277
5e4f7f74 278 // Populating contacts in members array based on their relationship with direct members.
6a488035
TO
279 if (!empty($relationships)) {
280 foreach ($relationships as $relTypeId => $membershipId) {
281 // As members are not direct members, there should not be
282 // membership id in the result array.
283 unset($membershipValues[$membershipId]['id']);
284 $relationship = new CRM_Contact_BAO_Relationship();
285 $relationship->contact_id_b = $contactID;
286 $relationship->relationship_type_id = $relTypeId;
287 if ($relationship->find()) {
288 while ($relationship->fetch()) {
289 clone($relationship);
290 $membershipValues[$membershipId]['contact_id'] = $relationship->contact_id_a;
291 $members[$membershipId]['related_contact_id'] = $relationship->contact_id_a;
292 }
293 }
294
295 }
296 }
37eda84b 297 return $members;
6a488035 298}