api/v3/Profile.php

   1 <?php
   2
   3 /*
   4   +--------------------------------------------------------------------+
   5   | CiviCRM version 4.4                                                |
   6   +--------------------------------------------------------------------+
   7   | Copyright CiviCRM LLC (c) 2004-2013                                |
   8   +--------------------------------------------------------------------+
   9   | This file is a part of CiviCRM.                                    |
  10   |                                                                    |
  11   | CiviCRM is free software; you can copy, modify, and distribute it  |
  12   | under the terms of the GNU Affero General Public License           |
  13   | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14   |                                                                    |
  15   | CiviCRM is distributed in the hope that it will be useful, but     |
  16   | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18   | See the GNU Affero General Public License for more details.        |
  19   |                                                                    |
  20   | You should have received a copy of the GNU Affero General Public   |
  21   | License and the CiviCRM Licensing Exception along                  |
  22   | with this program; if not, contact CiviCRM LLC                     |
  23   | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24   | GNU Affero General Public License or the licensing of CiviCRM,     |
  25   | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26   +--------------------------------------------------------------------+
  27 */
  28
  29 /**
  30  * File for the CiviCRM APIv3 activity profile functions
  31  *
  32  * @package CiviCRM_APIv3
  33  * @subpackage API_ActivityProfile
  34  * @copyright CiviCRM LLC (c) 2004-2013
  35  * @version $Id: ActivityProfile.php 30486 2011-05-20 16:12:09Z rajan $
  36  *
  37  */
  38
  39 /**
  40  * Retrieve Profile field values.
  41  *
  42  * @param array $params       Associative array of property name/value
  43  *                             pairs to get profile field values
  44  *
  45  * @throws API_Exception
  46  * @return Profile field values|CRM_Error
  47  *
  48  * NOTE this api is not standard & since it is tested we need to honour that
  49  * but the correct behaviour is for it to return an id indexed array as this supports
  50  * multiple instances - if a  single profile is passed in we will not return a normal api result array
  51  * in order to avoid breaking code. (This could still be confusing :-( but we have to keep the tested behaviour working
  52  *
  53  * Note that if contact_id is empty an array of defaults is returned
  54  */
  55 function civicrm_api3_profile_get($params) {
  56   $nonStandardLegacyBehaviour = is_numeric($params['profile_id']) ?  TRUE : FALSE;
  57   if(!empty($params['check_permissions']) && !empty($params['contact_id']) && !1 === civicrm_api3('contact', 'getcount', array('contact_id' => $params['contact_id'], 'check_permissions' => 1))) {
  58     throw new API_Exception('permission denied');
  59   }
  60   $profiles = (array) $params['profile_id'];
  61   $values = array();
  62   $ufGroupBAO = new CRM_Core_BAO_UFGroup();
  63   foreach ($profiles as $profileID) {
  64     $profileID = _civicrm_api3_profile_getProfileID($profileID);
  65     $values[$profileID] = array();
  66     if (strtolower($profileID) == 'billing') {
  67       $values[$profileID] = _civicrm_api3_profile_getbillingpseudoprofile($params);
  68       continue;
  69     }
  70     if(!CRM_Core_DAO::getFieldValue('CRM_Core_DAO_UFGroup', $profileID, 'is_active')) {
  71       throw new API_Exception('Invalid value for profile_id : ' . $profileID);
  72     }
  73
  74     $isContactActivityProfile = CRM_Core_BAO_UFField::checkContactActivityProfileType($profileID);
  75
  76     $profileFields = CRM_Core_BAO_UFGroup::getFields($profileID,
  77       FALSE,
  78       NULL,
  79       NULL,
  80       NULL,
  81       FALSE,
  82       NULL,
  83       empty($params['check_permissions']) ? FALSE : TRUE,
  84       NULL,
  85       CRM_Core_Permission::EDIT
  86     );
  87
  88
  89   if ($isContactActivityProfile) {
  90     civicrm_api3_verify_mandatory($params, NULL, array('activity_id'));
  91
  92     $errors = CRM_Profile_Form::validateContactActivityProfile($params['activity_id'],
  93       $params['contact_id'],
  94       $params['profile_id']
  95     );
  96     if (!empty($errors)) {
  97       throw new API_Exception(array_pop($errors));
  98     }
  99
 100     $contactFields = $activityFields = array();
 101     foreach ($profileFields as $fieldName => $field) {
 102       if (CRM_Utils_Array::value('field_type', $field) == 'Activity') {
 103         $activityFields[$fieldName] = $field;
 104       }
 105       else {
 106         $contactFields[$fieldName] = $field;
 107           // we should return 'Primary' with & without capitalisation. it is more consistent with api to not
 108           // capitalise, but for form support we need it for now. Hopefully we can move away from it
 109           $contactFields[strtolower($fieldName)] = $field;
 110         }
 111       }
 112
 113     $ufGroupBAO->setProfileDefaults($params['contact_id'], $contactFields, $values[$profileID], TRUE);
 114
 115     if ($params['activity_id']) {
 116       $ufGroupBAO->setComponentDefaults($activityFields, $params['activity_id'], 'Activity', $values[$profileID], TRUE);
 117     }
 118   }
 119   elseif(!empty($params['contact_id'])) {
 120     $ufGroupBAO->setProfileDefaults($params['contact_id'], $profileFields, $values[$profileID], TRUE);
 121       foreach ($values[$profileID] as $fieldName => $field){
 122         // we should return 'Primary' with & without capitalisation. it is more consistent with api to not
 123         // capitalise, but for form support we need it for now. Hopefully we can move away from it
 124         $values[$profileID][strtolower($fieldName)] = $field;
 125       }
 126     }
 127     else{
 128       $values[$profileID] = array_fill_keys(array_keys($profileFields), '');
 129     }
 130   }
 131   if($nonStandardLegacyBehaviour) {
 132     $result = civicrm_api3_create_success();
 133     $result['values'] = $values[$profileID];
 134     return $result;
 135   }
 136   else {
 137     return civicrm_api3_create_success($values, $params, 'Profile', 'Get');
 138   }
 139 }
 140
 141 function _civicrm_api3_profile_get_spec(&$params) {
 142   $params['profile_id']['api.required'] = TRUE;
 143   $params['contact_id']['description'] = 'If no contact is specified an array of defaults will be returned';
 144 }
 145
 146 /**
 147  * Submit a set of fields against a profile.
 148  * Note choice of submit versus create is discussed CRM-13234 & related to the fact
 149  * 'profile' is being treated as a data-entry entity
 150  *
 151  * @param array $params
 152  *
 153  * @throws API_Exception
 154  * @return array API result array
 155  */
 156 function civicrm_api3_profile_submit($params) {
 157   $profileID = _civicrm_api3_profile_getProfileID($params['profile_id']);
 158   if (!CRM_Core_DAO::getFieldValue('CRM_Core_DAO_UFGroup', $profileID, 'is_active')) {
 159     //@todo declare pseudoconstant & let api do this
 160     throw new API_Exception('Invalid value for profile_id');
 161   }
 162
 163   $isContactActivityProfile = CRM_Core_BAO_UFField::checkContactActivityProfileType($profileID);
 164
 165   if (!empty($params['id']) && CRM_Core_BAO_UFField::checkProfileType($profileID) && !$isContactActivityProfile) {
 166     throw new API_Exception('Update profiles including more than one entity not currently supported');
 167   }
 168
 169   $contactParams = $activityParams = $missingParams = array();
 170
 171   $profileFields = civicrm_api3('profile', 'getfields', array('action' => 'submit', 'profile_id' => $profileID));
 172   $profileFields = $profileFields['values'];
 173   if ($isContactActivityProfile) {
 174     civicrm_api3_verify_mandatory($params, NULL, array('activity_id'));
 175
 176     $errors = CRM_Profile_Form::validateContactActivityProfile($params['activity_id'],
 177       $params['contact_id'],
 178       $profileID
 179     );
 180     if (!empty($errors)) {
 181       throw new API_Exception(array_pop($errors));
 182     }
 183   }
 184
 185   foreach ($profileFields as $fieldName => $field) {
 186     if (!isset($params[$fieldName])) {
 187       continue;
 188     }
 189
 190     $value = $params[$fieldName];
 191     if ($params[$fieldName] && isset($params[$fieldName . '_id'])) {
 192       $value = $params[$fieldName . '_id'];
 193     }
 194     $contactEntities = array('contact', 'individual', 'organization', 'household');
 195     $locationEntities = array('email', 'address', 'phone', 'website', 'im');
 196
 197     $entity = strtolower(CRM_Utils_Array::value('entity', $field));
 198     if($entity && !in_array($entity, array_merge($contactEntities, $locationEntities))) {
 199       $contactParams['api.' . $entity . '.create'][$fieldName] = $value;
 200       //@todo we are not currently declaring this option
 201       if(isset($params['batch_id']) && strtolower($entity) == 'contribution') {
 202         $contactParams['api.' . $entity . '.create']['batch_id'] = $params['batch_id'];
 203       }
 204       if(isset($params[$entity . '_id'])) {
 205         //todo possibly declare $entity_id in getfields ?
 206         $contactParams['api.' . $entity . '.create']['id'] = $params[$entity . '_id'];
 207       }
 208     }
 209     else {
 210       $contactParams[_civicrm_api3_profile_translate_fieldnames_for_bao($fieldName)] = $value;
 211     }
 212   }
 213   if(isset($contactParams['api.contribution.create']) && isset($contactParams['api.membership.create'])) {
 214     $contactParams['api.membership_payment.create'] = array(
 215       'contribution_id' => '$value.api.contribution.create.id',
 216       'membership_id' => '$value.api.membership.create.id'
 217     );
 218   }
 219
 220   if(isset($contactParams['api.contribution.create']) && isset($contactParams['api.participant.create'])) {
 221     $contactParams['api.participant_payment.create'] = array(
 222       'contribution_id' => '$value.api.contribution.create.id',
 223       'participant_id' => '$value.api.participant.create.id'
 224     );
 225   }
 226
 227   $contactParams['contact_id'] = CRM_Utils_Array::value('contact_id', $params);
 228   $contactParams['profile_id'] = $profileID;
 229   $contactParams['skip_custom'] = 1;
 230
 231   $contactProfileParams = civicrm_api3_profile_apply($contactParams);
 232
 233   // Contact profile fields
 234   $profileParams = $contactProfileParams['values'];
 235
 236   // If profile having activity fields
 237   if ($isContactActivityProfile && !empty($activityParams)) {
 238     $activityParams['id'] = $params['activity_id'];
 239     $profileParams['api.activity.create'] = $activityParams;
 240   }
 241
 242   $groups = $tags = array();
 243   if (isset($profileParams['group'])) {
 244     $groups = $profileParams['group'];
 245     unset($profileParams['group']);
 246   }
 247
 248   if (isset($profileParams['tag'])) {
 249     $tags = $profileParams['tag'];
 250     unset($profileParams['tag']);
 251   }
 252
 253   return civicrm_api3('contact', 'create', $profileParams);
 254
 255   $ufGroupDetails = array();
 256   $ufGroupParams = array('id' => $profileID);
 257   CRM_Core_BAO_UFGroup::retrieve($ufGroupParams, $ufGroupDetails);
 258
 259   if (isset($profileFields['group'])) {
 260     CRM_Contact_BAO_GroupContact::create($groups,
 261       $params['contact_id'],
 262       FALSE,
 263       'Admin'
 264     );
 265   }
 266
 267   if (isset($profileFields['tag'])) {
 268     CRM_Core_BAO_EntityTag::create($tags,
 269       'civicrm_contact',
 270       $params['contact_id']
 271     );
 272   }
 273
 274   if (!empty($ufGroupDetails['add_to_group_id'])) {
 275     $contactIds = array($params['contact_id']);
 276     CRM_Contact_BAO_GroupContact::addContactsToGroup($contactIds,
 277       $ufGroupDetails['add_to_group_id']
 278     );
 279   }
 280
 281   return $result;
 282
 283 }
 284
 285 /**
 286  * The api standards expect field names to be lower case but the BAO uses mixed case
 287  * so we accept 'email-primary' but pass 'email-Primary' to the BAO
 288  * we could make the BAO handle email-primary but this would alter the fieldname seen by hooks
 289  * & we would need to consider that change
 290  * @param string $fieldName API field name
 291  *
 292  * @return string BAO Field Name
 293  */
 294 function _civicrm_api3_profile_translate_fieldnames_for_bao($fieldName){
 295   $fieldName = str_replace('url', 'URL', $fieldName);
 296   return str_replace('primary', 'Primary', $fieldName);
 297 }
 298 /**
 299  * metadata for submit action
 300  * @param array $params
 301  * @param array $apirequest
 302  */
 303 function _civicrm_api3_profile_submit_spec(&$params, $apirequest) {
 304   if(isset($apirequest['params']['profile_id'])) {
 305     // we will return what is required for this profile
 306     // note the problem with simply over-riding getfields & then calling generic if needbe is we don't have the
 307     // api request array to pass to it.
 308     //@todo - it may make more sense just to pass the apiRequest to getfields
 309     //@todo get_options should take an array - @ the moment it is only takes 'all' - which is supported
 310     // by other getfields fn
 311     // we don't resolve state, country & county for performance reasons
 312     $resolveOptions = CRM_Utils_Array::value('get_options',$apirequest['params']) == 'all' ? True : False;
 313     $profileID = _civicrm_api3_profile_getProfileID($apirequest['params']['profile_id']);
 314     $params = _civicrm_api3_buildprofile_submitfields($profileID, $resolveOptions, CRM_Utils_Array::value('cache_clear', $params));
 315   }
 316   elseif (isset($apirequest['params']['cache_clear'])) {
 317     _civicrm_api3_buildprofile_submitfields(FALSE, FALSE, True);
 318   }
 319   $params['profile_id']['api.required'] = TRUE;
 320 }
 321
 322 /**
 323  * @deprecated - calling this function directly is deprecated as 'set' is not a clear action
 324  * use submit
 325  * Update Profile field values.
 326  *
 327  * @param array  $params       Associative array of property name/value
 328  *                             pairs to update profile field values
 329  *
 330  * @return array Updated Contact/ Activity object|CRM_Error
 331  *
 332  *
 333  */
 334 function civicrm_api3_profile_set($params) {
 335   return civicrm_api3('profile', 'submit', $params);
 336 }
 337
 338 /**
 339  * @deprecated - appears to be an internal function - should not be accessible via api
 340  * Provide formatted values for profile fields.
 341  *
 342  * @param array $params       Associative array of property name/value
 343  *                             pairs to profile field values
 344  *
 345  * @throws API_Exception
 346  * @return formatted profile field values|CRM_Error
 347  *
 348  * @todo add example
 349  * @todo add test cases
 350  */
 351 function civicrm_api3_profile_apply($params) {
 352
 353   $profileFields = CRM_Core_BAO_UFGroup::getFields($params['profile_id'],
 354     FALSE,
 355     NULL,
 356     NULL,
 357     NULL,
 358     FALSE,
 359     NULL,
 360     TRUE,
 361     NULL,
 362     CRM_Core_Permission::EDIT
 363   );
 364
 365   list($data, $contactDetails) = CRM_Contact_BAO_Contact::formatProfileContactParams($params,
 366     $profileFields,
 367     CRM_Utils_Array::value('contact_id', $params),
 368     $params['profile_id'],
 369     CRM_Utils_Array::value('contact_type', $params),
 370     CRM_Utils_Array::value('skip_custom', $params, FALSE)
 371   );
 372
 373   if (empty($data)) {
 374     throw new API_Exception('Enable to format profile parameters.');
 375   }
 376
 377   return civicrm_api3_create_success($data);
 378 }
 379
 380
 381 /**
 382  * This is a function to help us 'pretend' billing is a profile & treat it like it is one.
 383  * It gets standard credit card address fields etc
 384  * Note this is 'better' that the inbuilt version as it will pull in fallback values
 385  *  billing location -> is_billing -> primary
 386  *
 387  *  Note that that since the existing code for deriving a blank profile is not easily accessible our
 388  *  interim solution is just to return an empty array
 389  *
 390  * @param $params
 391  *
 392  * @return array
 393  */
 394 function _civicrm_api3_profile_getbillingpseudoprofile(&$params) {
 395
 396   $locations = civicrm_api3('address', 'getoptions', array('field' => 'location_type_id'));
 397   $locationTypeID = array_search('Billing', $locations['values']);
 398
 399   if(empty($params['contact_id'])) {
 400     $config = CRM_Core_Config::singleton();
 401     $blanks =  array(
 402       'billing_first_name' => '',
 403       'billing_middle_name' => '',
 404       'billing_last_name' => '',
 405       'email-' . $locationTypeID => '',
 406       'billing_email-' . $locationTypeID => '',
 407       'billing_city-' . $locationTypeID => '',
 408       'billing_postal_code-' . $locationTypeID => '',
 409       'billing_street_address-' . $locationTypeID => '',
 410       'billing_country_id-' . $locationTypeID => $config->defaultContactCountry,
 411       'billing_state_province_id-' . $locationTypeID => $config->defaultContactStateProvince,
 412     );
 413     return $blanks;
 414   }
 415
 416   $addressFields = array('street_address', 'city', 'state_province_id', 'country_id', 'postal_code');
 417   $result = civicrm_api3('contact', 'getsingle', array(
 418     'id' => $params['contact_id'],
 419     'api.address.get.1' => array('location_type_id' => 'Billing',  'return' => $addressFields),
 420     // getting the is_billing required or not is an extra db call but probably cheap enough as this isn't an import api
 421     'api.address.get.2' => array('is_billing' => True, 'return' => $addressFields),
 422     'api.email.get.1' => array('location_type_id' => 'Billing',),
 423     'api.email.get.2' => array('is_billing' => True,),
 424     'return' => 'api.email.get, api.address.get, api.address.getoptions, country, state_province, email, first_name, last_name, middle_name, ' . implode($addressFields, ','),
 425    )
 426   );
 427
 428   $values = array(
 429     'billing_first_name' => $result['first_name'],
 430     'billing_middle_name' => $result['middle_name'],
 431     'billing_last_name' => $result['last_name'],
 432   );
 433
 434   if(!empty($result['api.address.get.1']['count'])) {
 435     foreach ($addressFields as $fieldname) {
 436       $values['billing_' . $fieldname . '-' . $locationTypeID] = isset($result['api.address.get.1']['values'][0][$fieldname])  ? $result['api.address.get.1']['values'][0][$fieldname] : '';
 437     }
 438   }
 439   elseif(!empty($result['api.address.get.2']['count'])) {
 440     foreach ($addressFields as $fieldname) {
 441       $values['billing_' . $fieldname . '-' . $locationTypeID] = isset($result['api.address.get.2']['values'][0][$fieldname])  ? $result['api.address.get.2']['values'][0][$fieldname] : '';
 442     }
 443   }
 444   else{
 445     foreach ($addressFields as $fieldname) {
 446       $values['billing_' . $fieldname . '-' . $locationTypeID] = isset($result[$fieldname]) ? $result[$fieldname] : '';
 447     }
 448   }
 449
 450   if(!empty($result['api.email.get.1']['count'])) {
 451     $values['billing-email'. '-' . $locationTypeID] = $result['api.email.get.1']['values'][0]['email'];
 452   }
 453   elseif(!empty($result['api.email.get.2']['count'])) {
 454     $values['billing-email'. '-' . $locationTypeID] = $result['api.email.get.2']['values'][0]['email'];
 455   }
 456   else{
 457     $values['billing-email'. '-' . $locationTypeID] = $result['email'];
 458   }
 459   // return both variants of email to reflect inconsistencies in form layer
 460   $values['email'. '-' . $locationTypeID] = $values['billing-email'. '-' . $locationTypeID];
 461   return $values;
 462 }
 463
 464 /**
 465  * Here we will build  up getfields type data for all the fields in the profile. Because the integration with the
 466  * form layer in core is so hard-coded we are not going to attempt to re-use it
 467  * However, as this function is unit-tested & hence 'locked in' we can aspire to extract sharable
 468  * code out of the form-layer over time.
 469  *
 470  * The function deciphers which fields belongs to which entites & retrieves metadata about the entities
 471  * Unfortunately we have inconsistencies such as 'contribution' uses contribution_status_id
 472  * & participant has 'participant_status' so we have to standardise from the outside in here -
 473  * find the oddities, 'mask them' at this layer, add tests & work to standardise over time so we can remove this handling
 474  *
 475  * @param integer $profileID
 476  * @param integer $optionsBehaviour 0 = don't resolve, 1 = resolve non-aggressively, 2 = resolve aggressively - ie include country & state
 477  * @param $is_flush
 478  *
 479  * @internal param $params
 480  *
 481  * @return
 482  */
 483
 484 function _civicrm_api3_buildprofile_submitfields($profileID, $optionsBehaviour = 1, $is_flush) {
 485   static $profileFields = array();
 486   if($is_flush) {
 487     $profileFields = array();
 488     if(empty($profileID)) {
 489       return;
 490     }
 491   }
 492   if(isset($profileFields[$profileID])) {
 493     return $profileFields[$profileID];
 494   }
 495   $fields = civicrm_api3('uf_field', 'get', array('uf_group_id' => $profileID));
 496   $entities = array();
 497   foreach ($fields['values'] as $field) {
 498     if(!$field['is_active']) {
 499       continue;
 500     }
 501     list($entity, $fieldName) = _civicrm_api3_map_profile_fields_to_entity($field);
 502     $aliasArray = array();
 503     if(strtolower($fieldName) != $fieldName) {
 504       $aliasArray['api.aliases'] = array($fieldName);
 505       $fieldName = strtolower($fieldName);
 506     }
 507     $profileFields[$profileID][$fieldName] = array_merge(array(
 508       'api.required' => $field['is_required'],
 509       'title' => $field['label'],
 510       'help_pre' => CRM_Utils_Array::value('help_pre', $field),
 511       'help_post' => CRM_Utils_Array::value('help_post', $field),
 512       'entity' => $entity,
 513       'weight' => CRM_Utils_Array::value('weight', $field),
 514     ), $aliasArray);
 515
 516     $ufFieldTaleFieldName = $field['field_name'];
 517     if(isset($entity[$ufFieldTaleFieldName]['name'])) {
 518       // in the case where we are dealing with an alias we map back to a name
 519       // this will be tested by 'membership_type_id' field
 520       $ufFieldTaleFieldName = $entity[$ufFieldTaleFieldName]['name'];
 521     }
 522     //see function notes
 523     // as we build up a list of these we should be able to determine a generic approach
 524     //
 525     $hardCodedEntityFields = array(
 526       'state_province' => 'state_province_id',
 527       'country' => 'country_id',
 528       'participant_status' => 'status_id',
 529       'gender' => 'gender_id',
 530       'financial_type' => 'financial_type_id',
 531       'soft_credit' => 'soft_credit_to',
 532       'group' => 'group_id',
 533       'tag' => 'tag_id',
 534       'soft_credit_type' => 'soft_credit_type_id',
 535     );
 536
 537     if(array_key_exists($ufFieldTaleFieldName, $hardCodedEntityFields)) {
 538       $ufFieldTaleFieldName = $hardCodedEntityFields[$ufFieldTaleFieldName];
 539     }
 540
 541     $entities[$entity][$fieldName] = $ufFieldTaleFieldName;
 542   }
 543
 544   foreach ($entities as $entity => $entityFields) {
 545     $result = civicrm_api3($entity, 'getfields', array('action' => 'create'));
 546     $entityGetFieldsResult = _civicrm_api3_profile_appendaliases($result['values'], $entity);
 547     foreach ($entityFields as $entityfield => $realName) {
 548       $fieldName = strtolower($entityfield);
 549       if(!strstr($fieldName, '-')) {
 550          if(strtolower($realName) != $fieldName) {
 551         // we want to keep the '-' pattern for locations but otherwise
 552         // we are going to make the api-standard field the main / preferred name but support the db name
 553         // in future naming the fields in the DB to reflect the way the rest of the api / BAO / metadata works would
 554         // reduce code
 555         $fieldName = strtolower($realName);
 556         }
 557         if(isset($entityGetFieldsResult[$realName]['uniqueName'])) {
 558           // we won't alias the field name on here are we are using uniqueNames for the possibility of needing to differentiate
 559           // which entity 'status_id' belongs to
 560           $fieldName = $entityGetFieldsResult[$realName]['uniqueName'];
 561         }
 562         else{
 563           if(isset($entityGetFieldsResult[$realName]['name'])) {
 564             // this will sort out membership_type_id vs membership_type
 565             $fieldName = $entityGetFieldsResult[$realName]['name'];
 566           }
 567         }
 568       }
 569       $profileFields[$profileID][$fieldName] = array_merge($entityGetFieldsResult[$realName], $profileFields[$profileID][$entityfield]);
 570       if(!isset($profileFields[$profileID][$fieldName]['api.aliases'])) {
 571        $profileFields[$profileID][$fieldName]['api.aliases'] = array();
 572       }
 573       if($optionsBehaviour && !empty($entityGetFieldsResult[$realName]['pseudoconstant'])) {
 574         if($optionsBehaviour > 1  || !in_array($realName, array('state_province_id', 'county_id', 'country_id'))) {
 575           $options = civicrm_api3($entity, 'getoptions', array('field' => $realName));
 576           $profileFields[$profileID][$fieldName]['options'] = $options['values'];
 577         }
 578       }
 579
 580       if($entityfield != $fieldName) {
 581         if(isset($profileFields[$profileID][$entityfield])) {
 582           unset($profileFields[$profileID][$entityfield]);
 583         }
 584         if(!in_array($entityfield, $profileFields[$profileID][$fieldName]['api.aliases'])) {
 585           // we will make the mixed case version (e.g. of 'Primary') an alias
 586           $profileFields[$profileID][$fieldName]['api.aliases'][] = $entityfield;
 587         }
 588       }
 589       /**
 590        * putting this on hold -this would cause the api to set the default - but could have unexpected behaviour
 591       if(isset($result['values'][$realName]['default_value'])) {
 592       //this would be the case for a custom field with a configured default
 593       $profileFields[$profileID][$entityfield]['api.default'] = $result['values'][$realName]['default_value'];
 594       }
 595        */
 596     }
 597   }
 598   uasort($profileFields[$profileID], "_civicrm_api3_order_by_weight");
 599   return $profileFields[$profileID];
 600 }
 601
 602 function _civicrm_api3_order_by_weight($a, $b) {
 603   return CRM_Utils_Array::value('weight', $b) < CRM_Utils_Array::value('weight', $a) ? TRUE : FALSE;
 604 }
 605
 606 /**
 607  * Here we map the profile fields as stored in the uf_field table to their 'real entity'
 608  * we also return the profile fieldname
 609  *
 610  * @param $field
 611  *
 612  * @return array
 613  */
 614 function _civicrm_api3_map_profile_fields_to_entity(&$field) {
 615   $entity = $field['field_type'];
 616   $contactTypes = civicrm_api3('contact', 'getoptions', array('field' => 'contact_type'));
 617   if(in_array($entity, $contactTypes['values'])) {
 618     $entity = 'contact';
 619   }
 620   $entity = _civicrm_api_get_entity_name_from_camel($entity);
 621   $locationFields = array('email' => 'email');
 622   $fieldName = $field['field_name'];
 623   if(!empty($field['location_type_id'])) {
 624     if($fieldName == 'email') {
 625       $entity = 'email';
 626     }
 627     else{
 628       $entity = 'address';
 629     }
 630     $fieldName .= '-' . $field['location_type_id'];
 631   }
 632   elseif(array_key_exists($fieldName, $locationFields)) {
 633     $fieldName .= '-Primary';
 634     $entity = 'email';
 635   }
 636   if(!empty($field['phone_type_id'])) {
 637     $fieldName .= '-' . $field['location_type_id'];
 638     $entity = 'phone';
 639   }
 640
 641   // @todo - sort this out!
 642   //here we do a hard-code list of known fields that don't map to where they are mapped to
 643   // not a great solution but probably if we looked in the BAO we'd find a scary switch statement
 644   // in a perfect world the uf_field table would hold the correct entity for each item
 645   // & only the relationships between entities would need to be coded
 646   $hardCodedEntityMappings = array(
 647     'street_address' => 'address',
 648     'street_number' => 'address',
 649     'supplemental_address_1' => 'address',
 650     'supplemental_address_2' => 'address',
 651     'supplemental_address_3' => 'address',
 652     'postal_code' => 'address',
 653     'city' => 'address',
 654     'email' => 'email',
 655     'state_province' => 'address',
 656     'country' => 'address',
 657     'county' => 'address',
 658     //note that in discussions about how to restructure the api we discussed making these membership
 659     // fields into 'membership_payment' fields - which would entail declaring them in getfields
 660     // & renaming them in existing profiles
 661     'financial_type' => 'contribution',
 662     'total_amount' => 'contribution',
 663     'receive_date' => 'contribution',
 664     'payment_instrument' => 'contribution',
 665     'check_number' => 'contribution',
 666     'contribution_status_id' => 'contribution',
 667     'soft_credit' => 'contribution',
 668     'soft_credit_type' => 'contribution_soft',
 669     'group' => 'group_contact',
 670     'tag' => 'entity_tag',
 671    );
 672   if(array_key_exists($fieldName, $hardCodedEntityMappings)) {
 673     $entity = $hardCodedEntityMappings[$fieldName];
 674   }
 675   return array($entity, $fieldName);
 676 }
 677
 678 /**
 679  * @todo this should be handled by the api wrapper using getfields info - need to check
 680  * how we add a a pseudoconstant to this pseudoapi to make that work
 681  */
 682 function _civicrm_api3_profile_getProfileID($profileID) {
 683   if(!empty($profileID) && strtolower($profileID) != 'billing' && !is_numeric($profileID)) {
 684     $profileID = civicrm_api3('uf_group', 'getvalue', array('return' => 'id', 'name' => $profileID));
 685   }
 686   return $profileID;
 687 }
 688
 689 /**
 690  * helper function to add all aliases as keys to getfields response so we can look for keys within it
 691  * since the relationship between profile fields & api / metadata based fields is a bit inconsistent
 692  *
 693  * @param array $values
 694  *
 695  * e.g getfields response incl 'membership_type_id' - with api.aliases = 'membership_type'
 696  * returned array will include both as keys (with the same values)
 697  * @param $entity
 698  *
 699  * @return array
 700  */
 701 function _civicrm_api3_profile_appendaliases($values, $entity) {
 702   foreach ($values as $field => $spec) {
 703     if(!empty($spec['api.aliases'])) {
 704       foreach ($spec['api.aliases'] as $alias) {
 705         $values[$alias] = $spec;
 706       }
 707     }
 708     if(!empty($spec['uniqueName'])) {
 709       $values[$spec['uniqueName']] = $spec;
 710     }
 711   }
 712   //special case on membership & contribution - can't see how to handle in a generic way
 713   if(in_array($entity, array('membership', 'contribution'))) {
 714     $values['send_receipt'] = array('title' => 'Send Receipt', 'type' => (int) 16);
 715   }
 716   return $values;
 717 }