/*
+--------------------------------------------------------------------+
- | CiviCRM version 4.3 |
+ | CiviCRM version 4.4 |
+--------------------------------------------------------------------+
| Copyright CiviCRM LLC (c) 2004-2013 |
+--------------------------------------------------------------------+
*
* NOTE this api is not standard & since it is tested we need to honour that
* but the correct behaviour is for it to return an id indexed array as this supports
- * multiple instances
+ * multiple instances - if a single profile is passed in we will not return a normal api result array
+ * in order to avoid breaking code. (This could still be confusing :-( but we have to keep the tested behaviour working
+ *
+ * Note that if contact_id is empty an array of defaults is returned
+ *
*/
function civicrm_api3_profile_get($params) {
$nonStandardLegacyBehaviour = is_numeric($params['profile_id']) ? TRUE : FALSE;
-
+ if(!empty($params['check_permissions']) && !empty($params['contact_id']) && !1 === civicrm_api3('contact', 'getcount', array('contact_id' => $params['contact_id'], 'check_permissions' => 1))) {
+ throw new API_Exception('permission denied');
+ }
$profiles = (array) $params['profile_id'];
$values = array();
foreach ($profiles as $profileID) {
+ $profileID = _civicrm_api3_profile_getProfileID($profileID);
$values[$profileID] = array();
if (strtolower($profileID) == 'billing') {
$values[$profileID] = _civicrm_api3_profile_getbillingpseudoprofile($params);
$isContactActivityProfile = CRM_Core_BAO_UFField::checkContactActivityProfileType($profileID);
- if (CRM_Core_BAO_UFField::checkProfileType($profileID) && !$isContactActivityProfile) {
- throw new API_Exception('Can not retrieve values for profiles include fields for more than one record type.');
- }
-
$profileFields = CRM_Core_BAO_UFGroup::getFields($profileID,
FALSE,
NULL,
NULL,
FALSE,
NULL,
- TRUE,
+ empty($params['check_permissions']) ? FALSE : TRUE,
NULL,
CRM_Core_Permission::EDIT
);
CRM_Core_BAO_UFGroup::setComponentDefaults($activityFields, $params['activity_id'], 'Activity', $values[$profileID], TRUE);
}
}
- else {
+ elseif(!empty($params['contact_id'])) {
CRM_Core_BAO_UFGroup::setProfileDefaults($params['contact_id'], $profileFields, $values[$profileID], TRUE);
}
+ else{
+ $values[$profileID] = array_fill_keys(array_keys($profileFields), '');
+ }
}
if($nonStandardLegacyBehaviour) {
$result = civicrm_api3_create_success();
function _civicrm_api3_profile_get_spec(&$params) {
$params['profile_id']['api.required'] = TRUE;
- // does this mean we use a different call to get a 'blank' profile?
- $params['contact_id']['api.required'] = TRUE;
+ $params['contact_id']['description'] = 'If no contact is specified an array of defaults will be returned';
}
+
/**
- * Update Profile field values.
- *
- * @param array $params Associative array of property name/value
- * pairs to update profile field values
- *
- * @return Updated Contact/ Activity object|CRM_Error
- *
- * @todo add example
- * @todo add test cases
- *
+ * Submit a set of fields against a profile.
+ * Note choice of submit versus create is discussed CRM-13234 & related to the fact
+ * 'profile' is being treated as a data-entry entity
+ * @param array $params
+ * @return array API result array
*/
-function civicrm_api3_profile_set($params) {
-
- civicrm_api3_verify_mandatory($params, NULL, array('profile_id'));
+function civicrm_api3_profile_submit($params) {
+ $profileID = _civicrm_api3_profile_getProfileID($params['profile_id']);
- if (!CRM_Core_DAO::getFieldValue('CRM_Core_DAO_UFGroup', $params['profile_id'], 'is_active')) {
+ if (!CRM_Core_DAO::getFieldValue('CRM_Core_DAO_UFGroup', $profileID, 'is_active')) {
+ //@todo declare pseudoconstant & let api do this
throw new API_Exception('Invalid value for profile_id');
}
- $isContactActivityProfile = CRM_Core_BAO_UFField::checkContactActivityProfileType($params['profile_id']);
+ $isContactActivityProfile = CRM_Core_BAO_UFField::checkContactActivityProfileType($profileID);
- if (CRM_Core_BAO_UFField::checkProfileType($params['profile_id']) && !$isContactActivityProfile) {
- throw new API_Exception('Can not retrieve values for profiles include fields for more than one record type.');
+ if (!empty($params['id']) && CRM_Core_BAO_UFField::checkProfileType($profileID) && !$isContactActivityProfile) {
+ throw new API_Exception('Update profiles including more than one entity not currently supported');
}
$contactParams = $activityParams = $missingParams = array();
- $profileFields = CRM_Core_BAO_UFGroup::getFields($params['profile_id'],
+ $profileFields = CRM_Core_BAO_UFGroup::getFields($profileID,
FALSE,
NULL,
NULL,
$errors = CRM_Profile_Form::validateContactActivityProfile($params['activity_id'],
$params['contact_id'],
- $params['profile_id']
+ $profileID
);
if (!empty($errors)) {
- return civicrm_api3_create_error(array_pop($errors));
+ throw new API_Exception(array_pop($errors));
}
}
throw new API_Exception("Missing required parameters for profile id {$params['profile_id']}: " . implode(', ', $missingParams));
}
- $contactParams['version'] = 3;
$contactParams['contact_id'] = CRM_Utils_Array::value('contact_id', $params);
- $contactParams['profile_id'] = $params['profile_id'];
+ $contactParams['profile_id'] = $profileID;
$contactParams['skip_custom'] = 1;
$contactProfileParams = civicrm_api3_profile_apply($contactParams);
return civicrm_api3('contact', 'create', $profileParams);
$ufGroupDetails = array();
- $ufGroupParams = array('id' => $params['profile_id']);
+ $ufGroupParams = array('id' => $profileID);
CRM_Core_BAO_UFGroup::retrieve($ufGroupParams, $ufGroupDetails);
if (isset($profileFields['group'])) {
}
return $result;
+
+}
+/**
+ * metadata for submit action
+ * @param array $params
+ * @param array $apirequest
+ */
+function _civicrm_api3_profile_submit_spec(&$params, $apirequest) {
+ if(isset($apirequest['params']['profile_id'])) {
+ // we will return what is required for this profile
+ // note the problem with simply over-riding getfields & then calling generic if needbe is we don't have the
+ // api request array to pass to it.
+ //@todo - it may make more sense just to pass the apiRequest to getfields
+ //@todo get_options should take an array - @ the moment it is only takes 'all' - which is supported
+ // by other getfields fn
+ // we don't resolve state, country & county for performance reasons
+ $resolveOptions = CRM_Utils_Array::value('get_options',$apirequest['params']) == 'all' ? True : False;
+ $profileID = _civicrm_api3_profile_getProfileID($apirequest['params']['profile_id']);
+ $params = _civicrm_api3_buildprofile_submitfields($profileID, $resolveOptions);
+ }
+ $params['profile_id']['api.required'] = TRUE;
+}
+
+/**
+ * @deprecated - calling this function directly is deprecated as 'set' is not a clear action
+ * use submit
+ * Update Profile field values.
+ *
+ * @param array $params Associative array of property name/value
+ * pairs to update profile field values
+ *
+ * @return Updated Contact/ Activity object|CRM_Error
+ *
+ *
+ */
+function civicrm_api3_profile_set($params) {
+ return civicrm_api3('profile', 'submit', $params);
}
/**
+ * @deprecated - appears to be an internal function - should not be accessible via api
* Provide formatted values for profile fields.
*
* @param array $params Associative array of property name/value
*/
function civicrm_api3_profile_apply($params) {
- civicrm_api3_verify_mandatory($params, NULL, array('profile_id'));
-
- if (!CRM_Core_DAO::getFieldValue('CRM_Core_DAO_UFGroup', $params['profile_id'], 'is_active')) {
- return civicrm_api3_create_error('Invalid value for profile_id');
- }
-
$profileFields = CRM_Core_BAO_UFGroup::getFields($params['profile_id'],
FALSE,
NULL,
return civicrm_api3_create_success($data);
}
-/**
- * Return UFGroup fields
- */
-function civicrm_api3_profile_getfields($params) {
- $dao = _civicrm_api3_get_DAO('UFGroup');
- $d = new $dao();
- $fields = $d->fields();
- return civicrm_api3_create_success($fields);
-}
/**
* This is a function to help us 'pretend' billing is a profile & treat it like it is one.
* It gets standard credit card address fields etc
* Note this is 'better' that the inbuilt version as it will pull in fallback values
* billing location -> is_billing -> primary
+ *
+ * Note that that since the existing code for deriving a blank profile is not easily accessible our
+ * interim solution is just to return an empty array
*/
function _civicrm_api3_profile_getbillingpseudoprofile(&$params) {
- $addressFields = array('street_address', 'city', 'state_province_id', 'country_id');
+ $addressFields = array('street_address', 'city', 'state_province_id', 'country_id', 'postal_code');
+ $locations = civicrm_api3('address', 'getoptions', array('field' => 'location_type_id'));
+ $locationTypeID = array_search('Billing', $locations['values']);
+
+ if(empty($params['contact_id'])) {
+ $blanks = array(
+ 'billing_first_name' => '',
+ 'billing_middle_name' => '',
+ 'billing_last_name' => '',
+ );
+ foreach ($addressFields as $field) {
+ $blanks['billing_' . $field . '_' . $locationTypeID] = '';
+ }
+ return $blanks;
+ }
$result = civicrm_api3('contact', 'getsingle', array(
'id' => $params['contact_id'],
- 'api.address.getoptions' => array('field' => 'location_type_id',),
'api.address.get.1' => array('location_type_id' => 'Billing', 'return' => $addressFields),
// getting the is_billing required or not is an extra db call but probably cheap enough as this isn't an import api
'api.address.get.2' => array('is_billing' => True, 'return' => $addressFields),
'api.email.get.1' => array('location_type_id' => 'Billing',),
'api.email.get.2' => array('is_billing' => True,),
- 'return' => 'api.email.get, api.address.get, api.address.getoptions, email, first_name, last_name, middle_name,' . implode($addressFields, ','),
+ 'return' => 'api.email.get, api.address.get, api.address.getoptions, country, state_province, email, first_name, last_name, middle_name, ' . implode($addressFields, ','),
)
);
- $locationTypeID = array_search('Billing', $result['api.address.getoptions']['values']);
$values = array(
'billing_first_name' => $result['first_name'],
else{
$values['billing-email'. '-' . $locationTypeID] = $result['email'];
}
+ // return both variants of email to reflect inconsistencies in form layer
+ $values['email'. '-' . $locationTypeID] = $values['billing-email'. '-' . $locationTypeID];
return $values;
}
+
+/**
+ * Here we will build up getfields type data for all the fields in the profile. Because the integration with the
+ * form layer in core is so hard-coded we are not going to attempt to re-use it
+ * However, as this function is unit-tested & hence 'locked in' we can aspire to extract sharable
+ * code out of the form-layer over time.
+ *
+ * The function deciphers which fields belongs to which entites & retrieves metadata about the entities
+ * Unfortunately we have inconsistencies such as 'contribution' uses contribution_status_id
+ * & participant has 'participant_status' so we have to standardise from the outside in here -
+ * find the oddities, 'mask them' at this layer, add tests & work to standardise over time so we can remove this handling
+ *
+ * @param integer $profileID
+ * @param integer $optionsBehaviour 0 = don't resolve, 1 = resolve non-aggressively, 2 = resolve aggressively - ie include country & state
+ */
+
+function _civicrm_api3_buildprofile_submitfields($profileID, $optionsBehaviour = 1) {
+ static $profileFields = array();
+ if(isset($profileFields[$profileID])) {
+ return $profileFields[$profileID];
+ }
+ $fields = civicrm_api3('uf_field', 'get', array('uf_group_id' => $profileID));
+ $entities = array();
+
+ foreach ($fields['values'] as $id => $field) {
+ if(!$field['is_active']) {
+ continue;
+ }
+ list($entity, $fieldName) = _civicrm_api3_map_profile_fields_to_entity($field);
+ $profileFields[$profileID][$fieldName] = array(
+ 'api.required' => $field['is_required'],
+ 'title' => $field['label'],
+ 'help_pre' => CRM_Utils_Array::value('help_pre', $field),
+ 'help_post' => CRM_Utils_Array::value('help_post', $field),
+ );
+
+ $realFieldName = $field['field_name'];
+ //see function notes
+ // as we build up a list of these we should be able to determine a generic approach
+ //
+ $hardCodedEntityFields = array(
+ 'state_province' => 'state_province_id',
+ 'country' => 'country_id',
+ 'participant_status' => 'status_id',
+ 'gender' => 'gender_id',
+ 'financial_type' => 'financial_type_id',
+ 'soft_credit' => 'soft_credit_to',
+ 'group' => 'group_id',
+ 'tag' => 'tag_id',
+ );
+
+ if(array_key_exists($realFieldName, $hardCodedEntityFields)) {
+ $realFieldName = $hardCodedEntityFields[$realFieldName];
+ }
+
+ $entities[$entity][$fieldName] = $realFieldName;
+ }
+
+ foreach ($entities as $entity => $entityFields) {
+ $result = civicrm_api3($entity, 'getfields', array('action' => 'create'));
+ $entityGetFieldsResult = _civicrm_api3_profile_appendaliases($result['values'], $entity);
+ foreach ($entityFields as $entityfield => $realName) {
+ $profileFields[$profileID][$entityfield] = $entityGetFieldsResult[$realName];
+ if($optionsBehaviour && !empty($entityGetFieldsResult[$realName]['pseudoconstant'])) {
+ if($optionsBehaviour > 1 || !in_array($realName, array('state_province_id', 'county_id', 'country_id'))) {
+ $options = civicrm_api3($entity, 'getoptions', array('field' => $realName));
+ $profileFields[$profileID][$entityfield]['options'] = $options['values'];
+ }
+ }
+ /**
+ * putting this on hold -this would cause the api to set the default - but could have unexpected behaviour
+ if(isset($result['values'][$realName]['default_value'])) {
+ //this would be the case for a custom field with a configured default
+ $profileFields[$profileID][$entityfield]['api.default'] = $result['values'][$realName]['default_value'];
+ }
+ */
+ }
+ }
+ return $profileFields[$profileID];
+}
+
+/**
+ * Here we map the profile fields as stored in the uf_field table to their 'real entity'
+ * we also return the profile fieldname
+ *
+ */
+function _civicrm_api3_map_profile_fields_to_entity(&$field) {
+ $entity = $field['field_type'];
+ $contactTypes = civicrm_api3('contact', 'getoptions', array('field' => 'contact_type'));
+ if(in_array($entity, $contactTypes['values'])) {
+ $entity = 'Contact';
+ }
+ $fieldName = $field['field_name'];
+ if(!empty($field['location_type_id'])) {
+ if($fieldName == 'email') {
+ $entity = 'Email';
+ }
+ else{
+ $entity = 'Address';
+ }
+ $fieldName .= '-' . $field['location_type_id'];
+ }
+ if(!empty($field['phone_type_id'])) {
+ $fieldName .= '-' . $field['location_type_id'];
+ $entity = 'Phone';
+ }
+ // @todo - sort this out!
+ //here we do a hard-code list of known fields that don't map to where they are mapped to
+ // not a great solution but probably if we looked in the BAO we'd find a scary switch statement
+ // in a perfect world the uf_field table would hold the correct entity for each item
+ // & only the relationships between entities would need to be coded
+ $hardCodedEntityMappings = array(
+ 'street_address' => 'Address',
+ 'street_number' => 'Address',
+ 'supplemental_address_1' => 'Address',
+ 'supplemental_address_2' => 'Address',
+ 'supplemental_address_3' => 'Address',
+ 'postal_code' => 'Address',
+ 'city' => 'Address',
+ 'email' => 'Email',
+ 'state_province' => 'Address',
+ 'country' => 'Address',
+ 'county' => 'Address',
+ //note that in discussions about how to restructure the api we discussed making these membership
+ // fields into 'membership_payment' fields - which would entail declaring them in getfields
+ // & renaming them in existing profiles
+ 'financial_type' => 'Contribution',
+ 'total_amount' => 'Contribution',
+ 'receive_date' => 'Contribution',
+ 'payment_instrument' => 'Contribution',
+ 'check_number' => 'Contribution',
+ 'contribution_status_id' => 'Contribution',
+ 'soft_credit' => 'Contribution',
+ 'group' => 'GroupContact',
+ 'tag' => 'EntityTag',
+ );
+ if(array_key_exists($fieldName, $hardCodedEntityMappings)) {
+ $entity = $hardCodedEntityMappings[$fieldName];
+ }
+ return array($entity, $fieldName);
+}
+
+/**
+ * @todo this should be handled by the api wrapper using getfields info - need to check
+ * how we add a a pseudoconstant to this pseudoapi to make that work
+ */
+function _civicrm_api3_profile_getProfileID($profileID) {
+ if(!empty($profileID) && strtolower($profileID) != 'billing' && !is_numeric($profileID)) {
+ $profileID = civicrm_api3('uf_group', 'getvalue', array('return' => 'id', 'name' => $profileID));
+ }
+ return $profileID;
+}
+
+/**
+ * helper function to add all aliases as keys to getfields response so we can look for keys within it
+ * since the relationship between profile fields & api / metadata based fields is a bit inconsistent
+ * @param array $values
+ *
+ * e.g getfields response incl 'membership_type_id' - with api.aliases = 'membership_type'
+ * returned array will include both as keys (with the same values)
+ */
+function _civicrm_api3_profile_appendaliases($values, $entity) {
+ foreach ($values as $field => $spec) {
+ if(!empty($spec['api.aliases'])) {
+ foreach ($spec['api.aliases'] as $alias) {
+ $values[$alias] = $spec;
+ }
+ }
+ if(!empty($spec['uniqueName'])) {
+ $values[$spec['uniqueName']] = $spec;
+ }
+ }
+ //special case on membership & contribution - can't see how to handle in a generic way
+ if(in_array($entity, array('Membership', 'Contribution'))) {
+ $values['send_receipt'] = array('title' => 'Send Receipt', 'type' => (int) 16);
+ }
+ return $values;
+}
\ No newline at end of file