api/v3/MembershipStatus.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM membership status.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Create a Membership Status.
  20  *
  21  * @param array $params
  22  *   Array of name/value property values of civicrm_membership_status.
  23  *
  24  * @return array
  25  */
  26 function civicrm_api3_membership_status_create($params) {
  27   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'MembershipStatus');
  28 }
  29
  30 /**
  31  * Adjust Metadata for Create action.
  32  *
  33  * The metadata is used for setting defaults, documentation & validation.
  34  *
  35  * @param array $params
  36  *   Array of parameters determined by getfields.
  37  */
  38 function _civicrm_api3_membership_status_create_spec(&$params) {
  39   $params['name']['api.required'] = 1;
  40 }
  41
  42 /**
  43  * Get a membership status.
  44  *
  45  * This api is used for finding an existing membership status.
  46  *
  47  * @param array $params
  48  *   An associative array of name/value property values of civicrm_membership_status.
  49  *
  50  * @return array
  51  *   Array of all found membership status property values.
  52  */
  53 function civicrm_api3_membership_status_get($params) {
  54   return _civicrm_api3_basic_get('CRM_Member_BAO_MembershipStatus', $params);
  55 }
  56
  57 /**
  58  * Update an existing membership status.
  59  *
  60  * This api is used for updating an existing membership status.
  61  * Required parameters: id of a membership status
  62  *
  63  * @param array $params
  64  *   Array of name/value property values of civicrm_membership_status.
  65  *
  66  * @deprecated - should just use create
  67  *
  68  * @return array
  69  *   Array of updated membership status property values
  70  */
  71 function civicrm_api3_membership_status_update($params) {
  72
  73   civicrm_api3_verify_mandatory($params, NULL, ['id']);
  74   //don't allow duplicate names.
  75   $name = CRM_Utils_Array::value('name', $params);
  76   if ($name) {
  77     $status = new CRM_Member_DAO_MembershipStatus();
  78     $status->name = $params['name'];
  79     if ($status->find(TRUE) && $status->id != $params['id']) {
  80       return civicrm_api3_create_error(ts('A membership status with this name already exists.'));
  81     }
  82   }
  83
  84   $membershipStatusBAO = new CRM_Member_BAO_MembershipStatus();
  85   $membershipStatusBAO->id = $params['id'];
  86   if ($membershipStatusBAO->find(TRUE)) {
  87     $fields = $membershipStatusBAO->fields();
  88     foreach ($fields as $name => $field) {
  89       if (array_key_exists($name, $params)) {
  90         $membershipStatusBAO->$name = $params[$name];
  91       }
  92     }
  93     $membershipStatusBAO->save();
  94   }
  95   $membershipStatus = [];
  96   $cloneBAO = clone($membershipStatusBAO);
  97   _civicrm_api3_object_to_array($cloneBAO, $membershipStatus);
  98   $membershipStatus['is_error'] = 0;
  99   return $membershipStatus;
 100 }
 101
 102 /**
 103  * Deletes an existing membership status.
 104  *
 105  * This API is used for deleting a membership status
 106  *
 107  * @param array $params
 108  * @return array
 109  * @throws API_Exception
 110  * @throws CRM_Core_Exception
 111  */
 112 function civicrm_api3_membership_status_delete($params) {
 113
 114   $memberStatusDelete = CRM_Member_BAO_MembershipStatus::del($params['id'], TRUE);
 115   if ($memberStatusDelete) {
 116     throw new API_Exception($memberStatusDelete['error_message']);
 117   }
 118   return civicrm_api3_create_success();
 119 }
 120
 121 /**
 122  * Derives the Membership Status of a given Membership Record.
 123  *
 124  * This API is used for deriving Membership Status of a given Membership
 125  * record using the rules encoded in the membership_status table.
 126  *
 127  * @param array $membershipParams
 128  *
 129  * @throws API_Exception
 130  *
 131  * @return array
 132  *   Array of status id and status name
 133  */
 134 function civicrm_api3_membership_status_calc($membershipParams) {
 135   if (!($membershipID = CRM_Utils_Array::value('membership_id', $membershipParams))) {
 136     throw new API_Exception('membershipParams do not contain membership_id');
 137   }
 138
 139   if (empty($membershipParams['id'])) {
 140     //for consistency lets make sure id is set as this will get passed to hooks downstream
 141     $membershipParams['id'] = $membershipID;
 142   }
 143   $query = "
 144 SELECT start_date, end_date, join_date, membership_type_id
 145   FROM civicrm_membership
 146  WHERE id = %1
 147 ";
 148
 149   $params = [1 => [$membershipID, 'Integer']];
 150   $dao = CRM_Core_DAO::executeQuery($query, $params);
 151   if ($dao->fetch()) {
 152     $membershipTypeID = empty($membershipParams['membership_type_id']) ? $dao->membership_type_id : $membershipParams['membership_type_id'];
 153     $result = CRM_Member_BAO_MembershipStatus::getMembershipStatusByDate($dao->start_date, $dao->end_date, $dao->join_date, 'today', CRM_Utils_Array::value('ignore_admin_only', $membershipParams), $membershipTypeID, $membershipParams);
 154     //make is error zero only when valid status found.
 155     if (!empty($result['id'])) {
 156       $result['is_error'] = 0;
 157     }
 158   }
 159   else {
 160     throw new API_Exception('did not find a membership record');
 161   }
 162   return $result;
 163 }
 164
 165 /**
 166  * Adjust Metadata for Calc action.
 167  *
 168  * The metadata is used for setting defaults, documentation & validation.
 169  *
 170  * @param array $params
 171  *   Array of parameters determined by getfields.
 172  */
 173 function _civicrm_api3_membership_status_calc_spec(&$params) {
 174   $params['membership_id']['api.required'] = 1;
 175   $params['membership_id']['title'] = 'Membership ID';
 176   $params['ignore_admin_only']['title'] = 'Ignore admin only statuses';
 177   $params['ignore_admin_only']['description'] = 'Ignore statuses that are for admin/manual assignment only';
 178   $params['ignore_admin_only']['type'] = CRM_Utils_Type::T_BOOLEAN;
 179 }