From 9d32e6f7cb94f1125e2dfc492b64701c929a8ece Mon Sep 17 00:00:00 2001 From: Eileen McNaughton Date: Mon, 2 Feb 2015 19:23:46 +1300 Subject: [PATCH] more comment fixes --- api/Wrapper.php | 4 + api/api.php | 6 +- api/v3/AclRole.php | 17 +--- api/v3/ActionSchedule.php | 7 +- api/v3/ActivityContact.php | 5 - api/v3/ActivityType.php | 9 +- api/v3/Batch.php | 12 +-- api/v3/CaseType.php | 20 ++-- api/v3/Contact.php | 37 +++---- api/v3/ContactType.php | 7 +- api/v3/Contribution.php | 25 +++-- api/v3/ContributionSoft.php | 19 ++-- api/v3/CustomGroup.php | 13 +-- api/v3/CustomSearch.php | 12 +-- api/v3/Domain.php | 13 +-- api/v3/Entity.php | 18 +++- api/v3/Extension.php | 3 +- api/v3/File.php | 17 +++- api/v3/FinancialAccount.php | 19 +--- api/v3/FinancialType.php | 19 +--- api/v3/Generic.php | 25 +++-- api/v3/GroupNesting.php | 2 - api/v3/GroupOrganization.php | 17 +--- api/v3/Location.php | 5 + api/v3/Mailing.php | 1 - api/v3/MailingAB.php | 1 - api/v3/MailingContact.php | 13 ++- api/v3/MailingGroup.php | 6 +- api/v3/MailingRecipients.php | 5 +- api/v3/MessageTemplate.php | 1 - api/v3/Note.php | 4 +- api/v3/OptionGroup.php | 12 +-- api/v3/OptionValue.php | 22 +--- api/v3/Participant.php | 31 +++--- api/v3/Pledge.php | 12 +-- api/v3/PledgePayment.php | 19 ++-- api/v3/Premium.php | 25 ++--- api/v3/PrintLabel.php | 19 +--- api/v3/Product.php | 19 +--- api/v3/Profile.php | 3 +- api/v3/Relationship.php | 16 +-- api/v3/RelationshipType.php | 13 ++- api/v3/ReportInstance.php | 6 +- api/v3/ReportTemplate.php | 26 ++--- api/v3/Setting.php | 9 +- api/v3/System.php | 17 ++-- api/v3/SystemLog.php | 13 ++- api/v3/UFField.php | 17 +--- api/v3/UFGroup.php | 18 ++-- api/v3/UFJoin.php | 3 +- api/v3/UFMatch.php | 20 ++-- api/v3/Website.php | 17 +--- api/v3/WordReplacement.php | 18 ++-- api/v3/utils.php | 191 +++++++++++++++++++++++++---------- 54 files changed, 422 insertions(+), 486 deletions(-) diff --git a/api/Wrapper.php b/api/Wrapper.php index 4df24d242f..6c9dad30e6 100644 --- a/api/Wrapper.php +++ b/api/Wrapper.php @@ -6,6 +6,8 @@ interface API_Wrapper { /** + * Interface for interpreting api input. + * * @param array $apiRequest * * @return array @@ -14,6 +16,8 @@ interface API_Wrapper { public function fromApiInput($apiRequest); /** + * Interface for interpreting api output. + * * @param array $apiRequest * @param array $result * diff --git a/api/api.php b/api/api.php index 3003f567c4..5b0a76c1d6 100644 --- a/api/api.php +++ b/api/api.php @@ -12,6 +12,8 @@ */ /** + * CiviCRM API wrapper function. + * * @param string $entity * type of entities to deal with * @param string $action @@ -27,7 +29,9 @@ function civicrm_api($entity, $action, $params, $extra = NULL) { } /** - * Version 3 wrapper for civicrm_api. Throws exception + * Version 3 wrapper for civicrm_api. + * + * Throws exception. * * @param string $entity * Type of entities to deal with. diff --git a/api/v3/AclRole.php b/api/v3/AclRole.php index 7c8763ef34..31775ea8c0 100644 --- a/api/v3/AclRole.php +++ b/api/v3/AclRole.php @@ -30,15 +30,12 @@ * * @package CiviCRM_APIv3 * @subpackage API_acl_role - * */ /** - * Save an acl_role + * Save an acl_role. * * Allowed @params array keys are: - * {@getfields acl_role_create} - * @example acl_roleCreate.php * * @param array $params * @@ -50,11 +47,7 @@ function civicrm_api3_acl_role_create($params) { } /** - * Get an acl_role - * - * Allowed @params array keys are: - * {@getfields acl_role_get} - * @example acl_roleCreate.php + * Get an acl_role. * * @param array $params * @@ -66,11 +59,7 @@ function civicrm_api3_acl_role_get($params) { } /** - * Delete an acl_role - * - * Allowed @params array keys are: - * {@getfields acl_role_delete} - * @example acl_roleCreate.php + * Delete an acl_role. * * @param array $params * diff --git a/api/v3/ActionSchedule.php b/api/v3/ActionSchedule.php index 5e7094b845..6fcd9cb1a5 100644 --- a/api/v3/ActionSchedule.php +++ b/api/v3/ActionSchedule.php @@ -47,13 +47,11 @@ function civicrm_api3_action_schedule_get($params) { /** - * Create a new Action Schedule + * Create a new Action Schedule. * * @param array $params * * @return array - * - * {@getfields action_schedule_create} */ function civicrm_api3_action_schedule_create($params) { civicrm_api3_verify_one_mandatory($params, NULL, array('start_action_date', 'absolute_date')); @@ -79,7 +77,7 @@ function _civicrm_api3_action_schedule_create_spec(&$params) { } /** - * delete an existing action_schedule + * Delete an existing action_schedule. * * @param array $params * Array containing id of the action_schedule. @@ -87,7 +85,6 @@ function _civicrm_api3_action_schedule_create_spec(&$params) { * * @return array * API result array - * */ function civicrm_api3_action_schedule_delete($params) { return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); diff --git a/api/v3/ActivityContact.php b/api/v3/ActivityContact.php index a2ea4899f6..991fb91e66 100644 --- a/api/v3/ActivityContact.php +++ b/api/v3/ActivityContact.php @@ -71,8 +71,6 @@ function _civicrm_api3_activity_contact_create_spec(&$params) { * * @return array * Api Result - * - * @example ActivityContact.php */ function civicrm_api3_activity_contact_delete($params) { return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); @@ -81,14 +79,11 @@ function civicrm_api3_activity_contact_delete($params) { /** * Get a ActivityContact. * - * @example ActivityContact.php - * * @param array $params * An associative array of name/value pairs. * * @return array * details of found tags else error - * */ function civicrm_api3_activity_contact_get($params) { return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params); diff --git a/api/v3/ActivityType.php b/api/v3/ActivityType.php index d1705c641a..6d2b4965a3 100644 --- a/api/v3/ActivityType.php +++ b/api/v3/ActivityType.php @@ -33,10 +33,11 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * $Id: ActivityType.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** + * Notification of deprecated function. + * * @deprecated api notice * @return string * to indicate this entire api entity is deprecated @@ -46,7 +47,7 @@ function _civicrm_api3_activity_type_deprecation() { } /** - * retrieve activity types + * Retrieve activity types. * * @param array $params * @@ -61,7 +62,7 @@ function civicrm_api3_activity_type_get($params) { } /** - * create activity type ( + * Create activity type. * * @param array $params * @@ -101,7 +102,7 @@ function _civicrm_api3_activity_type_create_spec(&$params) { } /** - * delete activity type + * Delete activity type. * * @param array $params * Array including id of activity_type to delete. diff --git a/api/v3/Batch.php b/api/v3/Batch.php index 1d527b70b7..d9524ffc51 100644 --- a/api/v3/Batch.php +++ b/api/v3/Batch.php @@ -66,11 +66,7 @@ function _civicrm_api3_batch_create_spec(&$params) { } /** - * Get a Batch - * - * Allowed @params array keys are: - * {@getfields batch_get} - * @example BatchCreate.php + * Get a Batch. * * @param array $params * @@ -82,11 +78,7 @@ function civicrm_api3_batch_get($params) { } /** - * Delete a Batch - * - * Allowed @params array keys are: - * {@getfields batch_delete} - * @example BatchCreate.php + * Delete a Batch. * * @param array $params * diff --git a/api/v3/CaseType.php b/api/v3/CaseType.php index 29d3af56a3..dfdf62d092 100644 --- a/api/v3/CaseType.php +++ b/api/v3/CaseType.php @@ -35,14 +35,11 @@ */ /** - * create or update case type + * Create or update case type. * * @param array $params * Input parameters. * - * Allowed @params array keys are: - * {@getfields case_type_create} - * * @throws API_Exception * @return array * API result array @@ -50,13 +47,15 @@ */ function civicrm_api3_case_type_create($params) { civicrm_api3_verify_mandatory($params, _civicrm_api3_get_DAO(__FUNCTION__)); - unset($params['is_forkable']); // computed property - unset($params['is_forked']); // computed property + // Computed properties. + unset($params['is_forkable']); + unset($params['is_forked']); if (!array_key_exists('is_active', $params) && empty($params['id'])) { $params['is_active'] = TRUE; } - if (!empty($params['id']) // this is an existing case-type + // This is an existing case-type. + if (!empty($params['id']) && !CRM_Case_BAO_CaseType::isForked($params['id']) // which is not yet forked && !CRM_Case_BAO_CaseType::isForkable($params['id']) // for which new forks are prohibited ) { @@ -67,7 +66,7 @@ function civicrm_api3_case_type_create($params) { } /** - * retrieve case types + * Retrieve case types. * * @param array $params * @@ -84,9 +83,10 @@ function civicrm_api3_case_type_get($params) { } /** - * format definition + * Format definition. * * @param array $result + * * @return array * @throws \CRM_Core_Exception */ @@ -107,7 +107,7 @@ function _civicrm_api3_case_type_get_formatResult(&$result) { } /** - * Function to delete case type + * Function to delete case type. * * @param array $params * Array including id of case_type to delete. diff --git a/api/v3/Contact.php b/api/v3/Contact.php index 3e33f35e78..4a33a5fe5b 100644 --- a/api/v3/Contact.php +++ b/api/v3/Contact.php @@ -34,21 +34,15 @@ * @subpackage API_Contact * @copyright CiviCRM LLC (c) 2004-2014 * $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $ - * */ /** - * Create or update a contact (note you should always call this via civicrm_api() & never directly) + * Create or update a contact (note you should always call this via civicrm_api() & never directly). * * @param array $params * Input parameters. * - * Allowed @params array keys are: - * {@getfields contact_create} - * - * * @throws API_Exception - * @example ContactCreate.php Example of Create Call * * @return array * API Result Array @@ -168,7 +162,7 @@ function civicrm_api3_contact_getcount($params) { } /** - * Adjust Metadata for Get action + * Adjust Metadata for Get action. * * @param array $params * Array or parameters determined by getfields. @@ -176,7 +170,7 @@ function civicrm_api3_contact_getcount($params) { function _civicrm_api3_contact_get_spec(&$params) { $params['contact_is_deleted']['api.default'] = 0; - //we declare all these pseudofields as there are other undocumented fields accessible + // We declare all these pseudoFields as there are other undocumented fields accessible // via the api - but if check permissions is set we only allow declared fields $params['address_id']['title'] = 'Primary Address ID'; $params['street_address']['title'] = 'Primary Address Street Address'; @@ -216,6 +210,8 @@ function _civicrm_api3_contact_get_spec(&$params) { } /** + * Support for historical oddities. + * * We are supporting 'showAll' = 'all', 'trash' or 'active' for contact get * and for getcount * - hopefully some day we'll come up with a std syntax for the 3-way-boolean of @@ -261,7 +257,7 @@ function _civicrm_api3_contact_get_supportanomalies(&$params, &$options) { } /** - * Delete a contact with given contact id + * Delete a contact with given contact id. * * @param array $params * input parameters per getfields @@ -296,6 +292,10 @@ function civicrm_api3_contact_delete($params) { /** + * Check parameters passed in. + * + * This function is on it's way out. + * * @param array $params * @param bool $dupeCheck * @@ -392,8 +392,7 @@ function _civicrm_api3_contact_check_params(&$params, $dupeCheck) { } /** - * Takes an associative array and creates a contact object and all the associated - * derived objects (i.e. individual, location, email, phone etc) + * Helper function for contact create. * * @param array $params * (reference ) an assoc array of name/value pairs. @@ -412,11 +411,10 @@ function _civicrm_api3_contact_update($params, $contactID = NULL) { } /** - * Validate the addressee or email or postal greetings + * Validate the addressee or email or postal greetings. * * @param array $params - * Associative array of property name/value. - * pairs to insert in new contact. + * Array per getfields metadata. * * @throws API_Exception * @@ -539,12 +537,12 @@ function _civicrm_api3_greeting_format_params($params) { } /** - * Old contact quick search api + * Old contact quick search api. * * @deprecated * - * {@example ContactGetquick.php 0} * @param array $params + * * @return array * @throws \API_Exception */ @@ -866,7 +864,6 @@ function _civicrm_api3_contact_deprecation() { * * @return array * API Result Array - * */ function civicrm_api3_contact_merge($params) { $mode = CRM_Utils_Array::value('mode', $params, 'safe'); @@ -887,6 +884,8 @@ function civicrm_api3_contact_merge($params) { } /** + * Adjust metadata for contact_proximity api function. + * * @param array $params */ function _civicrm_api3_contact_proximity_spec(&$params) { @@ -899,6 +898,8 @@ function _civicrm_api3_contact_proximity_spec(&$params) { } /** + * Get contacts by proximity. + * * @param array $params * * @return array diff --git a/api/v3/ContactType.php b/api/v3/ContactType.php index 4cffddfe82..5eb990eda5 100644 --- a/api/v3/ContactType.php +++ b/api/v3/ContactType.php @@ -34,7 +34,7 @@ */ /** - * create/update contact_type + * Create/update contact_type. * * This API is used to create new contact_type or update any of the existing * In case of updating existing contact_type, id of that particular contact_type must @@ -46,7 +46,6 @@ * * @return array * contact_type array - * */ function civicrm_api3_contact_type_create($params) { civicrm_api3_verify_mandatory($params, _civicrm_api3_get_DAO(__FUNCTION__), array('name', 'parent_id')); @@ -65,7 +64,7 @@ function civicrm_api3_contact_type_create($params) { } /** - * Returns array of contact_types matching a set of one or more group properties + * Returns array of contact_types matching a set of one or more group properties. * * @param array $params * One or more valid. @@ -81,7 +80,7 @@ function civicrm_api3_contact_type_get($params) { } /** - * delete an existing contact_type + * Delete an existing contact_type. * * This method is used to delete any existing contact_type. id of the group * to be deleted is required field in $params array diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php index 7f3265b3e2..5278e6614a 100644 --- a/api/v3/Contribution.php +++ b/api/v3/Contribution.php @@ -33,14 +33,13 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $ - * */ /** - * Add or update a contribution + * Add or update a contribution. * * @param array $params - * (reference ) input parameters. + * Input parameters. * * @throws API_Exception * @return array @@ -64,7 +63,7 @@ function civicrm_api3_contribution_create(&$params) { _civicrm_api3_contribution_create_legacy_support_45($params); - // make sure tax calculation is handled via api + // Make sure tax calculation is handled via api. $params = CRM_Contribute_BAO_Contribution::checkTaxAmount($params); return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution'); @@ -144,7 +143,8 @@ function _civicrm_api3_contribution_create_spec(&$params) { } /** - * Support for schema changes made in 4.5 + * Support for schema changes made in 4.5. + * * The main purpose of the API is to provide integrators a level of stability not provided by * the core code or schema - this means we have to provide support for api calls (where possible) * across schema changes. @@ -169,13 +169,12 @@ function _civicrm_api3_contribution_create_legacy_support_45(&$params) { } /** - * Delete a contribution + * Delete a contribution. * * @param array $params - * (reference ) input parameters. + * Input parameters. * - * @return bool - * true if success, else false + * @return array */ function civicrm_api3_contribution_delete($params) { @@ -189,7 +188,10 @@ function civicrm_api3_contribution_delete($params) { } /** - * modify metadata. Legacy support for contribution_id + * Modify metadata for delete action. + * + * Legacy support for contribution_id. + * * @param array $params */ function _civicrm_api3_contribution_delete_spec(&$params) { @@ -430,7 +432,8 @@ function civicrm_api3_contribution_completetransaction(&$params) { } /** - * provide function metadata + * Provide function metadata. + * * @param array $params */ function _civicrm_api3_contribution_completetransaction_spec(&$params) { diff --git a/api/v3/ContributionSoft.php b/api/v3/ContributionSoft.php index 781897805d..dcf39fe1e1 100644 --- a/api/v3/ContributionSoft.php +++ b/api/v3/ContributionSoft.php @@ -28,7 +28,7 @@ */ /** - * File for the CiviCRM APIv3 soft credit functions + * File for the CiviCRM APIv3 soft credit functions. * * @package CiviCRM_APIv3 * @subpackage API_ContributionSoft @@ -38,15 +38,13 @@ */ /** - * Create or Update a Soft Credit + * Create or Update a Soft Credit. * * @param array $params - * Associative array of property. - * name/value pairs to insert in new 'contribution_soft' + * Array per getfields metadata. * - * @example ContributionSoftCreate.php Standard Create Example //FIXME - * - * @return array API result array {@getfields contribution_soft_create} + * @return array + * API result array */ function civicrm_api3_contribution_soft_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); @@ -67,12 +65,9 @@ function _civicrm_api3_contribution_soft_create_spec(&$params) { } /** - * Deletes an existing Soft Credit + * Deletes an existing Soft Credit. * * @param array $params - * - * @example ContributionSoftDelete.php Standard Delete Example - * {@getfields contribution_soft_delete} */ function civicrm_api3_contribution_soft_delete($params) { // non standard BAO - we have to write custom code to cope @@ -81,7 +76,7 @@ function civicrm_api3_contribution_soft_delete($params) { } /** - * Retrieve one or more Soft Credits + * Retrieve one or more Soft Credits. * * @example ContributionSoftGet.php Standard Get Example * diff --git a/api/v3/CustomGroup.php b/api/v3/CustomGroup.php index 0f5e213ac9..672f98352c 100644 --- a/api/v3/CustomGroup.php +++ b/api/v3/CustomGroup.php @@ -44,20 +44,19 @@ * An associative array used in construction. * retrieval of the object * @todo missing get function - * - * */ /** - * Use this API to create a new group. The 'extends' value accepts an array or a comma separated string. + * Use this API to create a new group. + * + * The 'extends' value accepts an array or a comma separated string. * e.g array( 'Individual','Contact') or 'Individual,Contact' * See the CRM Data Model for custom_group property definitions * $params['class_name'] is a required field, class being extended. * * @param array $params - * Array Associative array of property name/value pairs to insert in group. - * {@getfields CustomGroup_create} + * Array of property name/value pairs to insert in group. * * @return array * @todo $params['extends'] is array format - is that std compatible @@ -121,8 +120,10 @@ function civicrm_api3_custom_group_get($params) { } /** - * CRM-15191 - Hack to ensure the cache gets cleared after updating a custom group + * CRM-15191 - Hack to ensure the cache gets cleared after updating a custom group. + * * @param array $params + * * @return array */ function civicrm_api3_custom_group_setvalue($params) { diff --git a/api/v3/CustomSearch.php b/api/v3/CustomSearch.php index 55197d9c33..3f34e85474 100644 --- a/api/v3/CustomSearch.php +++ b/api/v3/CustomSearch.php @@ -19,17 +19,12 @@ function civicrm_api3_custom_search_get($params) { } /** - * Add a CustomSearch - * - * Allowed @params array keys are: - * - * {@example OptionValueCreate.php} + * Add a CustomSearch. * * @param array $params * * @return array * Array of newly created option_value property values. - * {@getfields OptionValue_create} */ function civicrm_api3_custom_search_create($params) { require_once 'api/v3/OptionValue.php'; @@ -61,15 +56,12 @@ function _civicrm_api3_custom_search_create_spec(&$params) { } /** - * Deletes an existing ReportTemplate + * Deletes an existing ReportTemplate. * * @param array $params * - * {@example ReportTemplateDelete.php 0} - * * @return array * Api result - * {@getfields ReportTemplate_create} */ function civicrm_api3_custom_search_delete($params) { require_once 'api/v3/OptionValue.php'; diff --git a/api/v3/Domain.php b/api/v3/Domain.php index f39391d98c..950dcb4d4f 100644 --- a/api/v3/Domain.php +++ b/api/v3/Domain.php @@ -33,14 +33,13 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Domain.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** - * Get CiviCRM domain details - * {@getfields domain_create} - * @example DomainGet.php + * Get CiviCRM domain details. + * * @param array $params + * * @return array * @throws \API_Exception */ @@ -114,7 +113,7 @@ function civicrm_api3_domain_get($params) { } /** - * Adjust Metadata for Get action + * Adjust Metadata for Get action. * * The metadata is used for setting defaults, documentation & validation. * @@ -126,13 +125,11 @@ function _civicrm_api3_domain_get_spec(&$params) { } /** - * Create a new domain + * Create a new domain. * * @param array $params * * @return array - * @example DomainCreate.php - * {@getfields domain_create} */ function civicrm_api3_domain_create($params) { $params['version'] = $params['domain_version']; diff --git a/api/v3/Entity.php b/api/v3/Entity.php index 2621d17f45..ff3bb42511 100644 --- a/api/v3/Entity.php +++ b/api/v3/Entity.php @@ -23,8 +23,12 @@ function _civicrm_api3_entity_deprecation($entities) { } /** - * Placeholder function. This should never be called, as it doesn't have any meaning + * Placeholder function. + * + * This should never be called, as it doesn't have any meaning. + * * @param array $params + * * @return array */ function civicrm_api3_entity_create($params) { @@ -32,8 +36,12 @@ function civicrm_api3_entity_create($params) { } /** - * Placeholder function. This should never be called, as it doesn't have any meaning + * Placeholder function. + * + * This should never be called, as it doesn't have any meaning. + * * @param array $params + * * @return array */ function civicrm_api3_entity_delete($params) { @@ -41,8 +49,12 @@ function civicrm_api3_entity_delete($params) { } /** - * Placeholder function. This should never be called, as it doesn't have any meaning + * Placeholder function. + * + * This should never be called, as it doesn't have any meaning. + * * @param array $params + * * @return array */ function civicrm_api3_entity_getfields($params) { diff --git a/api/v3/Extension.php b/api/v3/Extension.php index 3646d416e0..6fd4a65a90 100644 --- a/api/v3/Extension.php +++ b/api/v3/Extension.php @@ -120,7 +120,7 @@ function civicrm_api3_extension_enable($params) { } /** - * Disable an extension + * Disable an extension. * * @param array $params * Input parameters. @@ -130,7 +130,6 @@ function civicrm_api3_extension_enable($params) { * * @return array * API result - * @example ExtensionDisable.php */ function civicrm_api3_extension_disable($params) { $keys = _civicrm_api3_getKeys($params); diff --git a/api/v3/File.php b/api/v3/File.php index a1a76ad823..c75c8e3e72 100644 --- a/api/v3/File.php +++ b/api/v3/File.php @@ -58,7 +58,15 @@ function civicrm_api3_file_create($params) { } $fileDAO = new CRM_Core_DAO_File(); - $properties = array('id', 'file_type_id', 'mime_type', 'uri', 'document', 'description', 'upload_date'); + $properties = array( + 'id', + 'file_type_id', + 'mime_type', + 'uri', + 'document', + 'description', + 'upload_date', + ); foreach ($properties as $name) { if (array_key_exists($name, $params)) { @@ -92,12 +100,12 @@ function civicrm_api3_file_get($params) { } /** - * Update an existing file + * Update an existing file. * * This api is used for updating an existing file. - * Required parameters : id of a file * * @param array $params + * * @return array */ function civicrm_api3_file_update($params) { @@ -121,10 +129,9 @@ function civicrm_api3_file_update($params) { } /** - * Deletes an existing file + * Delete an existing file. * * This API is used for deleting a file - * Required parameters : id of a file * * @param array $params * diff --git a/api/v3/FinancialAccount.php b/api/v3/FinancialAccount.php index 6445ff1ea3..96c708efbd 100644 --- a/api/v3/FinancialAccount.php +++ b/api/v3/FinancialAccount.php @@ -30,15 +30,10 @@ * * @package CiviCRM_APIv3 * @subpackage API_financial_account - * */ /** - * Save a financial_account - * - * Allowed @params array keys are: - * {@getfields financial_account_create} - * @example financial_accountCreate.php + * Save a financial_account. * * @param array $params * @@ -50,11 +45,7 @@ function civicrm_api3_financial_account_create($params) { } /** - * Get a financial_account - * - * Allowed @params array keys are: - * {@getfields financial_account_get} - * @example financial_accountCreate.php + * Get a financial_account. * * @param array $params * @@ -66,11 +57,7 @@ function civicrm_api3_financial_account_get($params) { } /** - * Delete a financial_account - * - * Allowed @params array keys are: - * {@getfields financial_account_delete} - * @example financial_accountCreate.php + * Delete a financial_account. * * @param array $params * diff --git a/api/v3/FinancialType.php b/api/v3/FinancialType.php index cc6466ebe5..1af8001aaf 100644 --- a/api/v3/FinancialType.php +++ b/api/v3/FinancialType.php @@ -30,15 +30,10 @@ * * @package CiviCRM_APIv3 * @subpackage API_financial_type - * */ /** - * Save a financial_type - * - * Allowed @params array keys are: - * {@getfields financial_type_create} - * @example financial_typeCreate.php + * Save a financial_type. * * @param array $params * @@ -50,11 +45,7 @@ function civicrm_api3_financial_type_create($params) { } /** - * Get a financial_type - * - * Allowed @params array keys are: - * {@getfields financial_type_get} - * @example financial_typeCreate.php + * Get a financial_type. * * @param array $params * @@ -66,11 +57,7 @@ function civicrm_api3_financial_type_get($params) { } /** - * Delete a financial_type - * - * Allowed @params array keys are: - * {@getfields financial_type_delete} - * @example financial_typeCreate.php + * Delete a financial_type. * * @param array $params * diff --git a/api/v3/Generic.php b/api/v3/Generic.php index 19863eabef..a19e1a9ff6 100644 --- a/api/v3/Generic.php +++ b/api/v3/Generic.php @@ -18,6 +18,7 @@ * - version: string * - function: callback (mixed) * - params: array, varies + * * @return array * API success object */ @@ -31,7 +32,11 @@ function civicrm_api3_generic_getfields($apiRequest) { CRM_Utils_PseudoConstant::flushConstant($apiRequest['params']['fieldname']); } if (!empty($apiRequest['params']['option_group_id'])) { - $optionGroupName = civicrm_api('option_group', 'getvalue', array('version' => 3, 'id' => $apiRequest['params']['option_group_id'], 'return' => 'name')); + $optionGroupName = civicrm_api('option_group', 'getvalue', array( + 'version' => 3, + 'id' => $apiRequest['params']['option_group_id'], + 'return' => 'name', + )); if (is_string($optionGroupName)) { CRM_Utils_PseudoConstant::flushConstant(_civicrm_api_get_camel_name($optionGroupName)); } @@ -145,7 +150,7 @@ function civicrm_api3_generic_getfields($apiRequest) { } /** - * API return function to reformat results as count + * API return function to reformat results as count. * * @param array $apiRequest * Api request as an array. Keys are. @@ -167,7 +172,7 @@ function civicrm_api3_generic_getcount($apiRequest) { } /** - * API return function to reformat results as single result + * API return function to reformat results as single result. * * @param array $apiRequest * Api request as an array. Keys are. @@ -176,7 +181,7 @@ function civicrm_api3_generic_getcount($apiRequest) { * count of results */ function civicrm_api3_generic_getsingle($apiRequest) { - // so the first entity is always result['values'][0] + // So the first entity is always result['values'][0]. $apiRequest['params']['sequential'] = 1; $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']); if ($result['is_error'] !== 0) { @@ -192,7 +197,7 @@ function civicrm_api3_generic_getsingle($apiRequest) { } /** - * API return function to reformat results as single value + * API return function to reformat results as single value. * * @param array $apiRequest * Api request as an array. Keys are. @@ -224,6 +229,8 @@ function civicrm_api3_generic_getvalue($apiRequest) { } /** + * Get count of contact references. + * * @param array $params */ function _civicrm_api3_generic_getrefcount_spec(&$params) { @@ -232,7 +239,7 @@ function _civicrm_api3_generic_getrefcount_spec(&$params) { } /** - * API to determine if a record is in-use + * API to determine if a record is in-use. * * @param array $apiRequest * Api request as an array. @@ -260,7 +267,7 @@ function civicrm_api3_generic_getrefcount($apiRequest) { } /** - * API wrapper for replace function + * API wrapper for replace function. * * @param array $apiRequest * Api request as an array. Keys are. @@ -273,7 +280,7 @@ function civicrm_api3_generic_replace($apiRequest) { } /** - * API wrapper for getoptions function + * API wrapper for getoptions function. * * @param array $apiRequest * Api request as an array. @@ -282,7 +289,7 @@ function civicrm_api3_generic_replace($apiRequest) { * Array of results */ function civicrm_api3_generic_getoptions($apiRequest) { - // Resolve aliases + // Resolve aliases. $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']); if (!$fieldName) { return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist."); diff --git a/api/v3/GroupNesting.php b/api/v3/GroupNesting.php index 5774099d2a..65640adcb4 100644 --- a/api/v3/GroupNesting.php +++ b/api/v3/GroupNesting.php @@ -33,7 +33,6 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: GroupNesting.php 21624 2009-08-07 22:02:55Z wmorgan $ - * */ /** @@ -41,7 +40,6 @@ * * @param array $params * An array containing at least child_group_id or parent_group_id. - * {@getfields GroupNesting_get} * * @return array * list of group nesting records diff --git a/api/v3/GroupOrganization.php b/api/v3/GroupOrganization.php index a21ea31797..7286dde362 100644 --- a/api/v3/GroupOrganization.php +++ b/api/v3/GroupOrganization.php @@ -33,31 +33,24 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: GroupContact.php 21624 2009-06-04 22:02:55Z mover $ - * */ /** - * This API will give list of the groups for particular contact - * Particualr status can be sent in params array - * If no status mentioned in params, by default 'added' will be used - * to fetch the records + * Get group organization record/s. * * @param array $params * Name value pair of contact information. - * {@getfields GroupOrganization_get} - * @example GroupOrganizationGet.php * * @return array - * list of groups, given contact subsribed to + * list of groups, given contact subscribed to */ function civicrm_api3_group_organization_get($params) { return _civicrm_api3_basic_get('CRM_Contact_DAO_GroupOrganization', $params); } /** - * @example GroupOrganizationCreate.php - * {@getfields GroupOrganization_create} + * Create group organization record. * * @param array $params * Array. @@ -91,7 +84,7 @@ function _civicrm_api3_group_organization_create_spec(&$params) { } /** - * Deletes an existing Group Organization + * Deletes an existing Group Organization. * * This API is used for deleting a Group Organization * @@ -100,8 +93,6 @@ function _civicrm_api3_group_organization_create_spec(&$params) { * * @return array * API Result - * {@getfields GroupOrganization_delete} - * @example GroupOrganizationDelete.php */ function civicrm_api3_group_organization_delete($params) { diff --git a/api/v3/Location.php b/api/v3/Location.php index 9f8ee7a661..31510dc7d9 100644 --- a/api/v3/Location.php +++ b/api/v3/Location.php @@ -4,6 +4,7 @@ * Function to inform caller that Location is obsolete and Address, Phone, Email, Website should be used. * * @param array $params + * * @return array */ function civicrm_api3_location_create($params) { @@ -11,6 +12,8 @@ function civicrm_api3_location_create($params) { } /** + * Function to inform caller that Location is obsolete and Address, Phone, Email, Website should be used. + * * @param array $params * * @return array @@ -20,6 +23,8 @@ function civicrm_api3_location_get($params) { } /** + * Function to inform caller that Location is obsolete and Address, Phone, Email, Website should be used. + * * @param array $params * * @return array diff --git a/api/v3/Mailing.php b/api/v3/Mailing.php index 653dce5d9b..432a48dfb6 100755 --- a/api/v3/Mailing.php +++ b/api/v3/Mailing.php @@ -33,7 +33,6 @@ * @subpackage API_Mailing * @copyright CiviCRM LLC (c) 2004-2014 * $Id$ - * */ /** diff --git a/api/v3/MailingAB.php b/api/v3/MailingAB.php index e7b9496bf5..888f08f764 100755 --- a/api/v3/MailingAB.php +++ b/api/v3/MailingAB.php @@ -33,7 +33,6 @@ * @subpackage API_MailingAB * @copyright CiviCRM LLC (c) 2004-2014 * $Id$ - * */ /** diff --git a/api/v3/MailingContact.php b/api/v3/MailingContact.php index 5ea8e89705..fa73be4eb1 100644 --- a/api/v3/MailingContact.php +++ b/api/v3/MailingContact.php @@ -33,11 +33,10 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id$ - * */ /** - * Get all the mailings and details that a contact was involved with + * Get all the mailings and details that a contact was involved with. * * @param array $params * Input parameters - see _spec for details (returned by getfields) @@ -49,10 +48,11 @@ function civicrm_api3_mailing_contact_get($params) { return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE)); } /** - * This is a wrapper for the functions that return the results from the 'quasi-entity' - * mailing contact + * This is a wrapper for the functions that return the results from the 'quasi-entity' mailing contact. + * * @param array $params * @param bool $count + * * @throws Exception */ function _civicrm_api3_mailing_contact_getresults($params, $count) { @@ -70,8 +70,9 @@ function _civicrm_api3_mailing_contact_getresults($params, $count) { $count ); } + /** - * Adjust Metadata for Get action + * Adjust Metadata for Get action. * * @param array $params * Array or parameters determined by getfields. @@ -91,6 +92,8 @@ function _civicrm_api3_mailing_contact_get_spec(&$params) { } /** + * Helper function for mailing contact queries. + * * @param int $contactID * @param $offset * @param $limit diff --git a/api/v3/MailingGroup.php b/api/v3/MailingGroup.php index 29c3acc388..407f0cafd5 100644 --- a/api/v3/MailingGroup.php +++ b/api/v3/MailingGroup.php @@ -46,7 +46,8 @@ function _civicrm_api3_mailing_group_deprecation() { } /** - * Handle an unsubscribe event + * Handle an unsubscribe event. + * * @deprecated * * @param array $params @@ -58,7 +59,8 @@ function civicrm_api3_mailing_group_event_unsubscribe($params) { } /** - * Handle a site-level unsubscribe event + * Handle a site-level unsubscribe event. + * * @deprecated * * @param array $params diff --git a/api/v3/MailingRecipients.php b/api/v3/MailingRecipients.php index 4a9332b413..f745f20388 100644 --- a/api/v3/MailingRecipients.php +++ b/api/v3/MailingRecipients.php @@ -33,15 +33,14 @@ * @subpackage API_Mailing * @copyright CiviCRM LLC (c) 2004-2014 * $Id$ - * */ /** - * Returns array of Mailing Recipients + * Returns array of Mailing Recipients. * * @param array $params - * Array of one or more valid. + * Array per getfields metadata. * * @return array * API return Array of matching mailing jobs diff --git a/api/v3/MessageTemplate.php b/api/v3/MessageTemplate.php index a030409a19..4c71eb9370 100644 --- a/api/v3/MessageTemplate.php +++ b/api/v3/MessageTemplate.php @@ -28,7 +28,6 @@ * File for the CiviCRM APIv3 message_template functions * * @package CiviCRM_SEPA - * */ /** diff --git a/api/v3/Note.php b/api/v3/Note.php index 22a9a9adeb..20e6cb40e4 100644 --- a/api/v3/Note.php +++ b/api/v3/Note.php @@ -85,7 +85,7 @@ function civicrm_api3_note_delete($params) { } /** - * Retrieve a specific note, given a set of input params + * Retrieve a specific note or notes, given a set of input params. * * @param array $params * Input parameters. @@ -93,8 +93,6 @@ function civicrm_api3_note_delete($params) { * @return array * array of properties, * if error an array with an error id and error message - * - * {@getfields note_get} */ function civicrm_api3_note_get($params) { diff --git a/api/v3/OptionGroup.php b/api/v3/OptionGroup.php index cfe6ed7a35..d3a5f495bd 100644 --- a/api/v3/OptionGroup.php +++ b/api/v3/OptionGroup.php @@ -12,19 +12,12 @@ function civicrm_api3_option_group_get($params) { } /** - * create/update survey - * - * This API is used to create new survey or update any of the existing - * In case of updating existing survey, id of that particular survey must - * be in $params array. + * Create/update option group. * * @param array $params - * (reference) Associative array of property. - * name/value pairs to insert in new 'survey' + * Array per getfields metadata. * * @return array - * survey array - * */ function civicrm_api3_option_group_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); @@ -54,7 +47,6 @@ function _civicrm_api3_option_group_create_spec(&$params) { * * @return array * API Result Array - * {@getfields OptionGroup_delete} */ function civicrm_api3_option_group_delete($params) { return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); diff --git a/api/v3/OptionValue.php b/api/v3/OptionValue.php index 3c1e5804a2..785ec02241 100644 --- a/api/v3/OptionValue.php +++ b/api/v3/OptionValue.php @@ -1,16 +1,12 @@ 3, 'id' => $params['id'], 'return' => 'option_group_id')); if (CRM_Core_BAO_OptionValue::del((int) $params['id'])) { civicrm_api('option_value', 'getfields', array('version' => 3, 'cache_clear' => 1, 'option_group_id' => $optionGroupID)); diff --git a/api/v3/Participant.php b/api/v3/Participant.php index 458863cd6e..0556d4f2c4 100644 --- a/api/v3/Participant.php +++ b/api/v3/Participant.php @@ -33,25 +33,19 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Participant.php 30486 2010-11-02 16:12:09Z shot $ - * */ /** - * Create an Event Participant - * - * This API is used for creating a participants in an event. - * Required parameters : event_id AND contact_id for new creation - * : participant as name/value with participantid for edit + * Create an Event Participant. * * @param array $params * An associative array of name/value property values of civicrm_participant. * * @return array - * apiresult - * {@getfields participant_create} + * API result array */ function civicrm_api3_participant_create($params) { - //check that event id is not an template - should be done @ BAO layer + // Check that event id is not an template - should be done @ BAO layer. if (!empty($params['event_id'])) { $isTemplate = CRM_Core_DAO::getFieldValue('CRM_Event_DAO_Event', $params['event_id'], 'is_template'); if (!empty($isTemplate)) { @@ -74,10 +68,13 @@ function civicrm_api3_participant_create($params) { } /** - * @todo this should be done in the BAO not the api * Create a default participant line item + * + * @todo this should be done in the BAO not the api + * * @param array $params * @param $participant + * * @throws \CiviCRM_API3_Exception */ function _civicrm_api3_participant_createlineitem(&$params, $participant) { @@ -155,16 +152,13 @@ function _civicrm_api3_participant_create_spec(&$params) { } /** - * Retrieve a specific participant, given a set of input params - * If more than one matching participant exists, return an error, unless - * the client has requested to return the first found contact + * Retrieve a specific participant, given a set of input params. * * @param array $params - * (reference ) input parameters. + * input parameters. * * @return array - * (reference ) array of properties, if error an array with an error id and error message - * {@getfields participant_get} + * array of properties, if error an array with an error id and error message */ function civicrm_api3_participant_get($params) { $mode = CRM_Contact_BAO_Query::MODE_EVENT; @@ -183,7 +177,7 @@ function civicrm_api3_participant_get($params) { } /** - * Adjust Metadata for Get action + * Adjust Metadata for Get action. * * The metadata is used for setting defaults, documentation & validation. * @@ -196,14 +190,13 @@ function _civicrm_api3_participant_get_spec(&$params) { } /** - * Deletes an existing contact participant + * Deletes an existing contact participant. * * This API is used for deleting a contact participant * * @param array $params * Array containing Id of the contact participant to be deleted. * - * {@getfields participant_delete} * @throws Exception * @return array */ diff --git a/api/v3/Pledge.php b/api/v3/Pledge.php index 1e3c340474..f03aec7373 100644 --- a/api/v3/Pledge.php +++ b/api/v3/Pledge.php @@ -33,26 +33,18 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Pledge.php - * */ /** - * Include utility functions + * Include utility functions. */ /** - * Creates or updates an Activity. See the example for usage - * - * @param array $params - * Associative array of property name/value. - * pairs for the activity. - * {@getfields pledge_create} + * Creates or updates an Pledge. * * @return array * Array containing 'is_error' to denote success or failure and details of the created pledge * - * @example PledgeCreate.php Standard create example - * */ function civicrm_api3_pledge_create($params) { _civicrm_api3_pledge_format_params($params, TRUE); diff --git a/api/v3/PledgePayment.php b/api/v3/PledgePayment.php index e36cd4840a..e6c83db083 100644 --- a/api/v3/PledgePayment.php +++ b/api/v3/PledgePayment.php @@ -33,11 +33,12 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: PledgePayment.php - * */ /** - * Add or update a pledge payment. Pledge Payment API doesn't actually add a pledge + * Add or update a pledge payment. + * + * Pledge Payment API doesn't actually add a pledge * if the request is to 'create' and 'id' is not passed in * the oldest pledge with no associated contribution is updated * @@ -46,8 +47,6 @@ * * @param array $params * Input parameters. - * {@getfields PledgePayment_create} - * @example PledgePaymentCreate.php * * @return array * API Result @@ -92,12 +91,10 @@ function _civicrm_api3_pledge_payment_create_spec(&$params) { } /** - * Delete a pledge Payment - Note this deletes the contribution not just the link + * Delete a pledge Payment - Note this deletes the contribution not just the link. * * @param array $params * Input parameters. - * {@getfields PledgePayment_delete} - * @example PledgePaymentDelete.php * * @return array * API result @@ -113,15 +110,13 @@ function civicrm_api3_pledge_payment_delete($params) { } /** - * Retrieve a set of pledges, given a set of input params + * Retrieve a set of pledges, given a set of input params. * * @param array $params * Input parameters. - * {@getfields PledgePayment_get} - * @example PledgePaymentGet.php * * * @return array - * (reference ) array of pledges, if error an array with an error id and error message + * array of pledges, if error an array with an error id and error message */ function civicrm_api3_pledge_payment_get($params) { @@ -129,7 +124,7 @@ function civicrm_api3_pledge_payment_get($params) { } /** - * Gets field for civicrm_pledge_payment functions + * Gets field for civicrm_pledge_payment functions. * * @param array $params * Modifiable list of fields allowed for the PledgePayment.get action. diff --git a/api/v3/Premium.php b/api/v3/Premium.php index 0e6ce88fe3..75d004343f 100644 --- a/api/v3/Premium.php +++ b/api/v3/Premium.php @@ -30,15 +30,10 @@ * * @package CiviCRM_APIv3 * @subpackage API_premium - * */ /** - * Save a premium - * - * Allowed @params array keys are: - * {@getfields premium_create} - * @example premiumCreate.php + * Save a premium. * * @param array $params * @@ -51,11 +46,7 @@ function civicrm_api3_premium_create($params) { } /** - * Get a premium - * - * Allowed @params array keys are: - * {@getfields premium_get} - * @example premiumCreate.php + * Get a premium. * * @param array $params * @@ -67,11 +58,7 @@ function civicrm_api3_premium_get($params) { } /** - * Delete a premium - * - * Allowed @params array keys are: - * {@getfields premium_delete} - * @example premiumCreate.php + * Delete a premium. * * @param array $params * @@ -84,7 +71,8 @@ function civicrm_api3_premium_delete($params) { } /** - * return field specification specific to get requests + * Return field specification specific to get requests. + * * @param array $params */ function _civicrm_api3_premium_get_spec(&$params) { @@ -92,7 +80,8 @@ function _civicrm_api3_premium_get_spec(&$params) { } /** - * return field specification specific to create requests + * Return field specification specific to create requests. + * * @param array $params */ function _civicrm_api3_premium_create_spec(&$params) { diff --git a/api/v3/PrintLabel.php b/api/v3/PrintLabel.php index c3f4dd27c3..87a487ed68 100644 --- a/api/v3/PrintLabel.php +++ b/api/v3/PrintLabel.php @@ -30,15 +30,10 @@ * * @package CiviCRM_APIv3 * @subpackage API_print_label - * */ /** - * Save a print_label - * - * Allowed @params array keys are: - * {@getfields print_label_create} - * @example print_labelCreate.php + * Save a print_label. * * @param array $params * @@ -50,11 +45,7 @@ function civicrm_api3_print_label_create($params) { } /** - * Get a print_label - * - * Allowed @params array keys are: - * {@getfields print_label_get} - * @example print_labelCreate.php + * Get a print_label. * * @param array $params * @@ -66,11 +57,7 @@ function civicrm_api3_print_label_get($params) { } /** - * Delete a print_label - * - * Allowed @params array keys are: - * {@getfields print_label_delete} - * @example print_labelCreate.php + * Delete a print_label. * * @param array $params * diff --git a/api/v3/Product.php b/api/v3/Product.php index 178d3a6764..28006d0d22 100644 --- a/api/v3/Product.php +++ b/api/v3/Product.php @@ -30,15 +30,10 @@ * * @package CiviCRM_APIv3 * @subpackage API_product - * */ /** - * Save a product - * - * Allowed @params array keys are: - * {@getfields product_create} - * @example productCreate.php + * Save a product. * * @param array $params * @@ -51,11 +46,7 @@ function civicrm_api3_product_create($params) { } /** - * Get a product - * - * Allowed @params array keys are: - * {@getfields product_get} - * @example productCreate.php + * Get a product. * * @param array $params * @@ -67,11 +58,7 @@ function civicrm_api3_product_get($params) { } /** - * Delete a product - * - * Allowed @params array keys are: - * {@getfields product_delete} - * @example productCreate.php + * Delete a product. * * @param array $params * diff --git a/api/v3/Profile.php b/api/v3/Profile.php index 034b12b36b..71d7d627ff 100644 --- a/api/v3/Profile.php +++ b/api/v3/Profile.php @@ -32,7 +32,6 @@ * @subpackage API_ActivityProfile * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Profile.php 30486 2011-05-20 16:12:09Z rajan $ - * */ /** @@ -138,6 +137,8 @@ function civicrm_api3_profile_get($params) { } /** + * Adjust profile get function metadata. + * * @param array $params */ function _civicrm_api3_profile_get_spec(&$params) { diff --git a/api/v3/Relationship.php b/api/v3/Relationship.php index cc336623ee..d0903b3adb 100644 --- a/api/v3/Relationship.php +++ b/api/v3/Relationship.php @@ -33,21 +33,18 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Relationship.php 30486 2010-11-02 16:12:09Z shot $ - * */ /** - * Add or update a relationship + * Add or update a relationship. * * @param array $params * Input parameters. * * @throws API_Exception - * @example RelationshipCreate.php Std Create example * * @return array * API Result Array - * {@getfields relationship_create} */ function civicrm_api3_relationship_create($params) { _civicrm_api3_handle_relationship_type($params); @@ -68,14 +65,12 @@ function _civicrm_api3_relationship_create_spec(&$params) { } /** - * Delete a relationship + * Delete a relationship. * * @param array $params * * @return array * API Result Array - * {@getfields relationship_delete} - * @example RelationshipDelete.php Delete Example * */ function civicrm_api3_relationship_delete($params) { @@ -96,18 +91,17 @@ function civicrm_api3_relationship_delete($params) { } /** - * get the relationship + * Get one or more relationship/s. * * @param array $params * Input parameters. + * * @todo Result is inconsistent depending on whether contact_id is passed in : * - if you pass in contact_id - it just returns all relationships for 'contact_id' * - if you don't pass in contact_id then it does a filter on the relationship table (DAO based search) * * @return array * API Result Array - * {@getfields relationship_get} - * @example RelationshipGet.php */ function civicrm_api3_relationship_get($params) { $options = _civicrm_api3_get_options_from_params($params); @@ -141,7 +135,7 @@ function civicrm_api3_relationship_get($params) { } /** - * legacy handling for relationship_type parameter + * Legacy handling for relationship_type parameter. * * @param array $params * Associative array of property name/value. diff --git a/api/v3/RelationshipType.php b/api/v3/RelationshipType.php index 45bd1f4d8a..8553e244aa 100644 --- a/api/v3/RelationshipType.php +++ b/api/v3/RelationshipType.php @@ -33,11 +33,10 @@ * @subpackage API_Contact * @copyright CiviCRM LLC (c) 2004-2014 * $Id: Contact.php 30415 2010-10-29 12:02:47Z shot $ - * */ /** - * create relationship type + * Create relationship type. * * @param array $params * Associative array of property name/value pairs to insert in new relationship type. @@ -90,10 +89,8 @@ function _civicrm_api3_relationship_type_create_spec(&$params) { } /** - * get all relationship type - * retruns An array of Relationship_type - * {@getfields RelationshipType_get} - * @example RelationshipTypeGet.php + * Get all relationship types. + * * @param array $params * @return array */ @@ -102,7 +99,7 @@ function civicrm_api3_relationship_type_get($params) { } /** - * Delete a relationship type delete + * Delete a relationship type. * * @param array $params * @@ -114,6 +111,8 @@ function civicrm_api3_relationship_type_delete($params) { } /** + * Get list defaults for relationship types. + * * @see _civicrm_api3_generic_getlist_defaults * * @param array $request diff --git a/api/v3/ReportInstance.php b/api/v3/ReportInstance.php index 64e5196ef0..fa34ae958a 100644 --- a/api/v3/ReportInstance.php +++ b/api/v3/ReportInstance.php @@ -1,20 +1,20 @@ value pairs. If $params is set - * as null, all surveys will be returned + * Array per getfields metadata. * * @return array - * (reference) Array - * {@getfields UFField_get - * @example UFFieldGet.php */ function civicrm_api3_uf_field_get($params) { return _civicrm_api3_basic_get('CRM_Core_BAO_UFField', $params); } /** - * Delete uf field + * Delete uf field. * * @param array $params * diff --git a/api/v3/UFGroup.php b/api/v3/UFGroup.php index c08a63b15d..a68efb0b27 100644 --- a/api/v3/UFGroup.php +++ b/api/v3/UFGroup.php @@ -33,10 +33,11 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: UFGroup.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** + * Adjust metadata for create action. + * * @param array $params */ function _civicrm_api3_uf_group_create_spec(&$params) { @@ -48,32 +49,30 @@ function _civicrm_api3_uf_group_create_spec(&$params) { $params['created_date']['api.default'] = 'now'; } /** - * Use this API to create a new group. See the CRM Data Model for uf_group property definitions + * Use this API to create a new group. + * + * See the CRM Data Model for uf_group property definitions * * @param array $params * Array Associative array of property name/value pairs to insert in group. * * @return array * API result array - * {@getfields UFGroup_create} - * @example UFGroupCreate.php */ function civicrm_api3_uf_group_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); } /** - * Returns array of uf groups (profiles) matching a set of one or more group properties + * Returns array of uf groups (profiles) matching a set of one or more group properties. * * @param array $params - * (reference) Array of one or more valid. + * Array of one or more valid. * property_name=>value pairs. If $params is set * as null, all surveys will be returned * * @return array * Array of matching profiles - * {@getfields UFGroup_get} - * @example UFGroupGet.php */ function civicrm_api3_uf_group_get($params) { @@ -81,11 +80,10 @@ function civicrm_api3_uf_group_get($params) { } /** - * Delete uf group + * Delete uf group. * * @param array $params * - * * @return array */ function civicrm_api3_uf_group_delete($params) { diff --git a/api/v3/UFJoin.php b/api/v3/UFJoin.php index 8dd21ffa80..fc164f74aa 100644 --- a/api/v3/UFJoin.php +++ b/api/v3/UFJoin.php @@ -33,11 +33,10 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: UFJoin.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** - * takes an associative array and creates a uf join in the database + * Takes an associative array and creates a uf join in the database. * * @param array $params * Assoc array of name/value pairs. diff --git a/api/v3/UFMatch.php b/api/v3/UFMatch.php index 447c34f2df..c4d69b6420 100644 --- a/api/v3/UFMatch.php +++ b/api/v3/UFMatch.php @@ -33,11 +33,10 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: UFGroup.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** - * get the contact_id given a uf_id or vice versa + * Get the contact_id given a uf_id or vice versa. * * @param array $params * @@ -48,16 +47,13 @@ function civicrm_api3_uf_match_get($params) { } /** - * Create or update a UF Match record + * Create or update a UF Match record. * * @param array $params - * Associative array of property. - * name/value pairs to insert in new 'survey' - * @example UFMatch.php Std Create example + * Array per getfields metadata. * * @return array - * api result array - * {@getfields uf_match_create} + * Api result array */ function civicrm_api3_uf_match_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); @@ -78,16 +74,12 @@ function _civicrm_api3_uf_match_create_spec(&$params) { } /** - * Create or update a survey + * Delete a UF Match record. * * @param array $params - * Associative array of property. - * name/value pairs to insert in new 'survey' - * @example UFMatch.php Std Create example * * @return array - * api result array - * {@getfields uf_match_create} + * Api result array. */ function civicrm_api3_uf_match_delete($params) { return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params); diff --git a/api/v3/Website.php b/api/v3/Website.php index be21414657..09ded9172a 100644 --- a/api/v3/Website.php +++ b/api/v3/Website.php @@ -36,12 +36,7 @@ */ /** - * Add an Website for a contact - * - * Allowed @params array keys are: - * {@getfields website_create} - * @example WebsiteCreate.php - * {@example WebsiteCreate.php} + * Add an Website for a contact. * * @param array $params * @@ -71,10 +66,11 @@ function _civicrm_api3_website_create_spec(&$params) { } /** - * Deletes an existing Website + * Deletes an existing Website. + * * @todo convert to using Basic delete - BAO function non standard * @param array $params - * {@getfields website_delete} + * * @return array * API result * @throws \API_Exception @@ -97,15 +93,12 @@ function civicrm_api3_website_delete($params) { } /** - * Retrieve one or more websites + * Retrieve one or more websites. * * @param array $params - * {@example WebsiteGet.php 0} - * @example WebsiteGet.php * * @return array * details of found websites - * */ function civicrm_api3_website_get($params) { return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, TRUE, 'website'); diff --git a/api/v3/WordReplacement.php b/api/v3/WordReplacement.php index 6b14d8b1f7..3a5bb451a7 100644 --- a/api/v3/WordReplacement.php +++ b/api/v3/WordReplacement.php @@ -33,13 +33,13 @@ * * @copyright CiviCRM LLC (c) 2004-2014 * @version $Id: Domain.php 30171 2010-10-14 09:11:27Z mover $ - * */ /** - * Get CiviCRM Word Replacement details - * {@getfields word_replacement_create} + * Get CiviCRM Word Replacement details. + * * @param array $params + * * @return array * @throws \API_Exception */ @@ -53,13 +53,11 @@ function civicrm_api3_word_replacement_get($params) { /** - * Create a new Word Replacement + * Create a new Word Replacement. * * @param array $params * * @return array - * - * {@getfields word_replacement_create} */ function civicrm_api3_word_replacement_create($params) { return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params); @@ -78,15 +76,13 @@ function _civicrm_api3_word_replacement_create_spec(&$params) { } /** - * delete an existing word_replacement - * + * Delete an existing word_replacement. * * @param array $params - * Array containing id of the word_replacement. - * to be deleted + * Array containing id of the word_replacement to be deleted. * * @return array - * api result array + * API result array * */ function civicrm_api3_word_replacement_delete($params) { diff --git a/api/v3/utils.php b/api/v3/utils.php index 08318765ea..6f5f3782b0 100644 --- a/api/v3/utils.php +++ b/api/v3/utils.php @@ -201,7 +201,24 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N $allFields = array_keys($apiFields['values']); } $paramFields = array_keys($params); - $undefined = array_diff($paramFields, $allFields, array_keys($_COOKIE), array('action', 'entity', 'debug', 'version', 'check_permissions', 'IDS_request_uri', 'IDS_user_agent', 'return', 'sequential', 'rowCount', 'option_offset', 'option_limit', 'custom', 'option_sort', 'options', 'prettyprint')); + $undefined = array_diff($paramFields, $allFields, array_keys($_COOKIE), array( + 'action', + 'entity', + 'debug', + 'version', + 'check_permissions', + 'IDS_request_uri', + 'IDS_user_agent', + 'return', + 'sequential', + 'rowCount', + 'option_offset', + 'option_limit', + 'custom', + 'option_sort', + 'options', + 'prettyprint', + )); if ($undefined) { $result['undefined_fields'] = array_merge($undefined); } @@ -237,20 +254,22 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N $result['values'] = $values; } if (!empty($params['options']['metadata'])) { - // we've made metadata an array but only supporting 'fields' atm + // We've made metadata an array but only supporting 'fields' atm. if (in_array('fields', (array) $params['options']['metadata']) && $action !== 'getfields') { - $fields = civicrm_api3($entity, 'getfields', array('action' => substr($action, 0, 3) == 'get' ? 'get' : 'create')); + $fields = civicrm_api3($entity, 'getfields', array( + 'action' => substr($action, 0, 3) == 'get' ? 'get' : 'create', + )); $result['metadata']['fields'] = $fields['values']; } } - // Report deprecations + // Report deprecations. $deprecated = _civicrm_api3_deprecation_check($entity, $result); - // Always report "update" action as deprecated + // Always report "update" action as deprecated. if (!is_string($deprecated) && ($action == 'getactions' || $action == 'update')) { $deprecated = ((array) $deprecated) + array('update' => 'The "update" action is deprecated. Use "create" with an id instead.'); } if ($deprecated) { - // Metadata-level deprecations or wholesale entity deprecations + // Metadata-level deprecations or wholesale entity deprecations. if ($entity == 'entity' || $action == 'getactions' || is_string($deprecated)) { $result['deprecated'] = $deprecated; } @@ -266,6 +285,7 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N * Load the DAO of the entity. * * @param $entity + * * @return bool */ function _civicrm_api3_load_DAO($entity) { @@ -653,7 +673,8 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) { } if (!empty($options['return']) && is_array($options['return']) && empty($options['is_count'])) { $dao->selectAdd(); - $options['return']['id'] = TRUE;// ensure 'id' is included + // Ensure 'id' is included. + $options['return']['id'] = TRUE; $allfields = _civicrm_api3_get_unique_name_array($dao); $returnMatched = array_intersect(array_keys($options['return']), $allfields); foreach ($returnMatched as $returnValue) { @@ -668,7 +689,8 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) { $returnUniqueMatched = array_intersect( $unmatchedFields, - array_flip($allfields)// but a match for the field keys + // But a match for the field keys. + array_flip($allfields) ); foreach ($returnUniqueMatched as $uniqueVal) { $dao->selectAdd($allfields[$uniqueVal]); @@ -708,12 +730,13 @@ function _civicrm_api3_apply_filters_to_dao($filterField, $filterValue, &$dao) { /** * Get sort, limit etc options from the params - supporting old & new formats. - * get returnproperties for legacy + * + * Get returnProperties for legacy * * @param array $params * Params array as passed into civicrm_api. * @param bool $queryObject - * Is this supporting a queryobject api (e.g contact) - if so we support more options. + * Is this supporting a queryObject api (e.g contact) - if so we support more options. * for legacy report & return a unique fields array * * @param string $entity @@ -814,7 +837,7 @@ function _civicrm_api3_get_options_from_params(&$params, $queryObject = FALSE, $ } /** - * Apply options (e.g. sort, limit, order by) to DAO object (prior to find) + * Apply options (e.g. sort, limit, order by) to DAO object (prior to find). * * @param array $params * Params array as passed into civicrm_api. @@ -836,7 +859,9 @@ function _civicrm_api3_apply_options_to_dao(&$params, &$dao, $entity) { } /** - * build fields array. This is the array of fields as it relates to the given DAO + * Build fields array. + * + * This is the array of fields as it relates to the given DAO * returns unique fields as keys by default but if set but can return by DB fields * * @param CRM_Core_DAO $bao @@ -862,7 +887,9 @@ function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) { } /** - * build fields array. This is the array of fields as it relates to the given DAO + * Build fields array. + * + * This is the array of fields as it relates to the given DAO * returns unique fields as keys by default but if set but can return by DB fields * * @param CRM_Core_DAO $bao @@ -878,7 +905,7 @@ function _civicrm_api3_get_unique_name_array(&$bao) { } /** - * Converts an DAO object to an array + * Converts an DAO object to an array. * * @param CRM_Core_DAO $dao * Object to convert. @@ -971,9 +998,11 @@ function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) { } /** - * Wrapper for _civicrm_object_to_array when api supports unique fields + * Wrapper for _civicrm_object_to_array when api supports unique fields. + * * @param $dao * @param $values + * * @return array */ function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) { @@ -981,6 +1010,7 @@ function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) { } /** + * Format custom parameters. * * @param array $params * @param array $values @@ -1019,6 +1049,8 @@ function _civicrm_api3_custom_format_params($params, &$values, $extends, $entity } /** + * Format parameters for create action. + * * @param array $params * @param $entity */ @@ -1035,7 +1067,9 @@ function _civicrm_api3_format_params_for_create(&$params, $entity) { } /** - * we can't rely on downstream to add separators to checkboxes so we'll check here. We should look at pushing to BAO function + * We can't rely on downstream to add separators to checkboxes so we'll check here. + * + * We should look at pushing to BAO function * and / or validate function but this is a safe place for now as it has massive test coverage & we can keep the change very specific * note that this is specifically tested in the GRANT api test case so later refactoring should use that as a checking point * @@ -1053,20 +1087,19 @@ function _civicrm_api3_format_params_for_create(&$params, $entity) { * @todo - we are probably skipping handling disabled options as presumably getoptions is not giving us them. This should be non-regressive but might * be fixed in future * - * @param $checkboxFieldValue - * @param $customFieldLabel - * @param $entity - * + * @param mixed $checkboxFieldValue + * @param string $customFieldLabel + * @param string $entity */ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) { if (is_string($checkboxFieldValue) && stristr($checkboxFieldValue, CRM_Core_DAO::VALUE_SEPARATOR)) { - // we can assume it's pre-formatted + // We can assume it's pre-formatted. return; } $options = civicrm_api($entity, 'getoptions', array('field' => $customFieldLabel, 'version' => 3)); if (!empty($options['is_error'])) { - //the check is precautionary - can probably be removed later + // The check is precautionary - can probably be removed later. return; } @@ -1130,14 +1163,15 @@ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) { } /** + * This function ensures that we have the right input parameters. + * * @deprecated - * This function ensures that we have the right input parameters * * This function is only called when $dao is passed into verify_mandatory. * The practice of passing $dao into verify_mandatory turned out to be - * unsatisfactory as the required fields @ the dao level is so diffent to the abstract + * unsatisfactory as the required fields @ the dao level is so different to the abstract * api level. Hence the intention is to remove this function - * & the associated param from viery_mandatory + * & the associated param from verify_mandatory * * @param array $params * Associative array of property name/value. @@ -1148,7 +1182,7 @@ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) { * @daoName string DAO to check params agains * * @return bool - * Sshould the missing fields be returned as an array (core error created as default) + * Should the missing fields be returned as an array (core error created as default) * true if all fields present, depending on $result a core error is created of an array of missing fields is returned */ function _civicrm_api3_check_required_fields($params, $daoName, $return = FALSE) { @@ -1196,7 +1230,7 @@ function _civicrm_api3_check_required_fields($params, $daoName, $return = FALSE) } /** - * Function to do a 'standard' api get - when the api is only doing a $bao->find then use this + * Function to do a 'standard' api get - when the api is only doing a $bao->find then use this. * * @param string $bao_name * Name of BAO. @@ -1220,7 +1254,7 @@ function _civicrm_api3_basic_get($bao_name, &$params, $returnAsSuccess = TRUE, $ } /** - * Function to do a 'standard' api create - when the api is only doing a $bao::create then use this + * Function to do a 'standard' api create - when the api is only doing a $bao::create then use this. * * @param string $bao_name * Name of BAO Class. @@ -1285,7 +1319,9 @@ function _civicrm_api3_basic_create($bao_name, &$params, $entity = NULL) { * @param array $params * * @throws API_Exception - * @return CRM_Core_DAO|NULL an instance of the BAO + * + * @return CRM_Core_DAO|NULL + * An instance of the BAO */ function _civicrm_api3_basic_create_fallback($bao_name, &$params) { $dao_name = get_parent_class($bao_name); @@ -1310,8 +1346,9 @@ function _civicrm_api3_basic_create_fallback($bao_name, &$params) { } /** - * Function to do a 'standard' api del - when the api is only doing a $bao::del then use this - * if api::del doesn't exist it will try DAO delete method + * Function to do a 'standard' api del. + * + * When the api is only doing a $bao::del then use this if api::del doesn't exist it will try DAO delete method. * * @param string $bao_name * @param array $params @@ -1349,7 +1386,10 @@ function _civicrm_api3_basic_delete($bao_name, &$params) { } /** - * Get custom data for the given entity & Add it to the returnArray as 'custom_123' = 'custom string' AND 'custom_123_1' = 'custom string' + * Get custom data for the given entity & Add it to the returnArray. + * + * This looks like 'custom_123' = 'custom string' AND + * 'custom_123_1' = 'custom string' * Where 123 is field value & 1 is the id within the custom group data table (value ID) * * @param array $returnArray @@ -1398,11 +1438,14 @@ function _civicrm_api3_custom_data_get(&$returnArray, $entity, $entity_id, $grou } /** - * Validate fields being passed into API. This function relies on the getFields function working accurately + * Validate fields being passed into API. + * + * This function relies on the getFields function working accurately * for the given API. If error mode is set to TRUE then it will also check * foreign keys * * As of writing only date was implemented. + * * @param string $entity * @param string $action * @param array $params @@ -1411,6 +1454,7 @@ function _civicrm_api3_custom_data_get(&$returnArray, $entity, $entity_id, $grou * Response from getfields all variables are the same as per civicrm_api. * @param bool $errorMode * ErrorMode do intensive post fail checks?. + * * @throws Exception */ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $errorMode = FALSE) { @@ -1471,6 +1515,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err /** * Validate date fields being passed into API. + * * It currently converts both unique fields and DB field names to a mysql date. * @todo - probably the unique field handling & the if exists handling is now done before this * function is reached in the wrapper - can reduce this code down to assume we @@ -1485,6 +1530,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err * Uniquename of field being checked. * @param array $fieldInfo * Array of fields from getfields function. + * * @throws Exception */ function _civicrm_api3_validate_date(&$params, &$fieldName, &$fieldInfo) { @@ -1509,8 +1555,9 @@ function _civicrm_api3_validate_date(&$params, &$fieldName, &$fieldInfo) { } /** - * convert date into BAO friendly date - * we accept 'whatever strtotime accepts' + * Convert date into BAO friendly date. + * + * We accept 'whatever strtotime accepts' * * @param string $dateValue * @param string $fieldName @@ -1541,6 +1588,7 @@ function _civicrm_api3_getValidDate($dateValue, $fieldName, $fieldType) { * Uniquename of field being checked. * @param array $fieldInfo * Array of fields from getfields function. + * * @throws \API_Exception */ function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInfo) { @@ -1561,6 +1609,7 @@ function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInf * Params from civicrm_api. * @param string $fieldName * Uniquename of field being checked. + * * @throws Exception */ function _civicrm_api3_validate_unique_key(&$params, &$fieldName) { @@ -1593,7 +1642,8 @@ function _civicrm_api3_validate_unique_key(&$params, &$fieldName) { * @param array $params * Params from civicrm_api, including:. * - 'values': an array of records to save - * - all other items: keys which identify new/pre-existing records + * - all other items: keys which identify new/pre-existing records. + * * @return array|int */ function _civicrm_api3_generic_replace($entity, $params) { @@ -1659,9 +1709,11 @@ function _civicrm_api3_generic_replace($entity, $params) { } /** + * Replace base parameters. + * * @param array $params * - * @return mixed + * @return array */ function _civicrm_api3_generic_replace_base_params($params) { $baseParams = $params; @@ -1672,7 +1724,7 @@ function _civicrm_api3_generic_replace_base_params($params) { } /** - * returns fields allowable by api + * Returns fields allowable by api. * * @param $entity * String Entity to query. @@ -1683,7 +1735,13 @@ function _civicrm_api3_generic_replace_base_params($params) { * @return array */ function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array()) { - $unsetIfEmpty = array('dataPattern', 'headerPattern', 'default', 'export', 'import'); + $unsetIfEmpty = array( + 'dataPattern', + 'headerPattern', + 'default', + 'export', + 'import', + ); $dao = _civicrm_api3_get_DAO($entity); if (empty($dao)) { return array(); @@ -1726,10 +1784,13 @@ function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array()) { } /** - * Return an array of fields for a given entity - this is the same as the BAO function but - * fields are prefixed with 'custom_' to represent api params + * Return an array of fields for a given entity. + * + * This is the same as the BAO function but fields are prefixed with 'custom_' to represent api params. + * * @param $entity * @param array $params + * * @return array */ function _civicrm_api_get_custom_fields($entity, &$params) { @@ -1762,8 +1823,10 @@ function _civicrm_api_get_custom_fields($entity, &$params) { } /** - * Translate the custom field data_type attribute into a std 'type' + * Translate the custom field data_type attribute into a std 'type'. + * * @param $dataType + * * @return int */ function _getStandardTypeFromCustomDataType($dataType) { @@ -1786,10 +1849,12 @@ function _getStandardTypeFromCustomDataType($dataType) { /** - * Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't + * Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't. + * * If multiple aliases the last takes precedence * * Function also swaps unique fields for non-unique fields & vice versa. + * * @param $apiRequest * @param $fields */ @@ -1829,7 +1894,8 @@ function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) { /** * Validate integer fields being passed into API. - * It currently converts the incoming value 'user_contact_id' into the id of the currently logged in user + * + * It currently converts the incoming value 'user_contact_id' into the id of the currently logged in user. * * @param array $params * Params from civicrm_api. @@ -1838,6 +1904,7 @@ function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) { * @param array $fieldInfo * Array of fields from getfields function. * @param string $entity + * * @throws API_Exception */ function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $entity) { @@ -1886,14 +1953,15 @@ function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $ent } /** - * Determine a contact ID using a string expression + * Determine a contact ID using a string expression. * * @param string $contactIdExpr * E.g. "user_contact_id" or "@user:username". + * * @return int|NULL|'unknown-user' */ function _civicrm_api3_resolve_contactID($contactIdExpr) { - //if value = 'user_contact_id' replace value with logged in user id + // If value = 'user_contact_id' replace value with logged in user id. if ($contactIdExpr == "user_contact_id") { return CRM_Core_Session::getLoggedInContactID(); } @@ -1916,7 +1984,8 @@ function _civicrm_api3_resolve_contactID($contactIdExpr) { } /** - * Validate html (check for scripting attack) + * Validate html (check for scripting attack). + * * @param array $params * @param string $fieldName * @param array $fieldInfo @@ -1937,6 +2006,7 @@ function _civicrm_api3_validate_html(&$params, &$fieldName, $fieldInfo) { /** * Validate string fields being passed into API. + * * @param array $params * Params from civicrm_api. * @param string $fieldName @@ -1944,6 +2014,7 @@ function _civicrm_api3_validate_html(&$params, &$fieldName, $fieldInfo) { * @param array $fieldInfo * Array of fields from getfields function. * @param string $entity + * * @throws API_Exception * @throws Exception */ @@ -1993,12 +2064,13 @@ function _civicrm_api3_validate_string(&$params, &$fieldName, &$fieldInfo, $enti } /** - * Validate & swap out any pseudoconstants / options + * Validate & swap out any pseudoconstants / options. * * @param mixed $fieldValue * @param string $entity : api entity name * @param string $fieldName : field name used in api call (not necessarily the canonical name) * @param array $fieldInfo : getfields meta-data + * * @throws \API_Exception */ function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldName, $fieldInfo) { @@ -2006,20 +2078,24 @@ function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldNam if (!$options) { if (strtolower($entity) == 'profile' && !empty($fieldInfo['entity'])) { - // we need to get the options from the entity the field relates to + // We need to get the options from the entity the field relates to. $entity = $fieldInfo['entity']; } - $options = civicrm_api($entity, 'getoptions', array('version' => 3, 'field' => $fieldInfo['name'], 'context' => 'validate')); + $options = civicrm_api($entity, 'getoptions', array( + 'version' => 3, + 'field' => $fieldInfo['name'], + 'context' => 'validate', + )); $options = CRM_Utils_Array::value('values', $options, array()); } - // If passed a value-separated string, explode to an array, then re-implode after matching values + // If passed a value-separated string, explode to an array, then re-implode after matching values. $implode = FALSE; if (is_string($fieldValue) && strpos($fieldValue, CRM_Core_DAO::VALUE_SEPARATOR) !== FALSE) { $fieldValue = CRM_Utils_Array::explodePadded($fieldValue); $implode = TRUE; } - // If passed multiple options, validate each + // If passed multiple options, validate each. if (is_array($fieldValue)) { foreach ($fieldValue as &$value) { if (!is_array($value)) { @@ -2039,11 +2115,12 @@ function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldNam } /** - * Validate & swap a single option value for a field + * Validate & swap a single option value for a field. * * @param string $value field value * @param array $options array of options for this field * @param string $fieldName field name used in api call (not necessarily the canonical name) + * * @throws API_Exception */ function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldName) { @@ -2070,7 +2147,7 @@ function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldN } /** - * Returns the canonical name of a field + * Returns the canonical name of a field. * * @param $entity * api entity name (string should already be standardized - no camelCase). @@ -2110,8 +2187,11 @@ function _civicrm_api3_api_resolve_alias($entity, $fieldName) { } /** + * Check if the function is deprecated. + * * @param string $entity * @param array $result + * * @return string|array|null */ function _civicrm_api3_deprecation_check($entity, $result = array()) { @@ -2129,11 +2209,14 @@ function _civicrm_api3_deprecation_check($entity, $result = array()) { } /** + * Get the actual field value. + * * In some case $params[$fieldName] holds Array value in this format Array([operator] => [value]) * So this function returns the actual field value * * @param array $params * @param string $fieldName + * * @return mixed */ function _civicrm_api3_field_value_check(&$params, $fieldName) { -- 2.25.1