From 44b74a670f7b160efaa4c6305d90ea6bbb95bc4d Mon Sep 17 00:00:00 2001 From: eileenmcnaugton Date: Mon, 25 Jan 2016 21:31:31 +1300 Subject: [PATCH] Sync comments between master & 4.6 branches for easier patching --- CRM/Contact/BAO/Query.php | 136 ++++++++++++++++----------- CRM/Contact/Form/Search/Advanced.php | 1 + CRM/Core/BAO/CustomQuery.php | 15 +-- CRM/Core/DAO.php | 39 ++------ 4 files changed, 95 insertions(+), 96 deletions(-) diff --git a/CRM/Contact/BAO/Query.php b/CRM/Contact/BAO/Query.php index f9efcaaf50..6057b2a2d9 100644 --- a/CRM/Contact/BAO/Query.php +++ b/CRM/Contact/BAO/Query.php @@ -29,8 +29,6 @@ * * @package CRM * @copyright CiviCRM LLC (c) 2004-2015 - * $Id$ - * */ /** @@ -463,8 +461,6 @@ class CRM_Contact_BAO_Query { /** * Function which actually does all the work for the constructor. - * - * @return void */ public function initialize() { $this->_select = array(); @@ -504,6 +500,23 @@ class CRM_Contact_BAO_Query { $this->openedSearchPanes(TRUE); } + /** + * Function for same purpose as convertFormValues. + * + * Like convert form values this function exists to pre-Process parameters from the form. + * + * It is unclear why they are different functions & likely relates to advances search + * versus search builder. + * + * The direction we are going is having the form convert values to a standardised format & + * moving away from wierd & wonderful where clause switches. + * + * Fix and handle contact deletion nicely. + * + * this code is primarily for search builder use case where different clauses can specify if they want deleted. + * + * CRM-11971 + */ public function buildParamsLookup() { // first fix and handle contact deletion nicely // this code is primarily for search builder use case @@ -568,10 +581,7 @@ class CRM_Contact_BAO_Query { } /** - * Some composite fields do not appear in the fields array - * hack to make them part of the query - * - * @return void + * Some composite fields do not appear in the fields array hack to make them part of the query. */ public function addSpecialFields() { static $special = array('contact_type', 'contact_sub_type', 'sort_name', 'display_name'); @@ -589,8 +599,6 @@ class CRM_Contact_BAO_Query { * clauses. Note that since the where clause introduces new * tables, the initial attempt also retrieves all variables used * in the params list - * - * @return void */ public function selectClause() { @@ -912,6 +920,8 @@ class CRM_Contact_BAO_Query { CRM_Contact_BAO_Query_Hook::singleton()->alterSearchQuery($this, 'select'); if (!empty($this->_cfIDs)) { + // @todo This function is the select function but instead of running 'select' it + // is running the whole query. $this->_customQuery = new CRM_Core_BAO_CustomQuery($this->_cfIDs, TRUE, $this->_locationSpecificCustomFields); $this->_customQuery->query(); $this->_select = array_merge($this->_select, $this->_customQuery->_select); @@ -923,10 +933,7 @@ class CRM_Contact_BAO_Query { } /** - * If the return Properties are set in a hierarchy, traverse the hierarchy to get - * the return values - * - * @return void + * If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values. */ public function addHierarchicalElements() { if (empty($this->_returnProperties['location'])) { @@ -1257,10 +1264,7 @@ class CRM_Contact_BAO_Query { } /** - * If the return Properties are set in a hierarchy, traverse the hierarchy to get - * the return values - * - * @return void + * If the return Properties are set in a hierarchy, traverse the hierarchy to get the return values. */ public function addMultipleElements() { if (empty($this->_returnProperties['website'])) { @@ -1407,12 +1411,14 @@ class CRM_Contact_BAO_Query { } /** + * Get where values from the parameters. + * * @param string $name - * @param $grouping + * @param mixed $grouping * - * @return null + * @return mixed */ - public function &getWhereValues($name, $grouping) { + public function getWhereValues($name, $grouping) { $result = NULL; foreach ($this->_params as $values) { if ($values[0] == $name && $values[3] == $grouping) { @@ -1424,9 +1430,11 @@ class CRM_Contact_BAO_Query { } /** - * @param $relative - * @param $from - * @param $to + * Fix date values. + * + * @param bool $relative + * @param string $from + * @param string $to */ public static function fixDateValues($relative, &$from, &$to) { if ($relative) { @@ -1435,7 +1443,28 @@ class CRM_Contact_BAO_Query { } /** - * @param $formValues + * Convert values from form-appropriate to query-object appropriate. + * + * The query object is increasingly supporting the sql-filter syntax which is the most flexible syntax. + * So, ideally we would convert all fields to look like + * array( + * 0 => $fieldName + * // Set the operator for legacy reasons, but it is ignored + * 1 => '=' + * // array in sql filter syntax + * 2 => array('BETWEEN' => array(1,60), + * 3 => null + * 4 => null + * ); + * + * There are some examples of the syntax in + * https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples/Relationship + * + * More notes at CRM_Core_DAO::createSQLFilter + * + * and a list of supported operators in CRM_Core_DAO + * + * @param array $formValues * @param int $wildcard * @param bool $useEquals * @@ -1507,7 +1536,7 @@ class CRM_Contact_BAO_Query { /** * @param int $id - * @param $values + * @param array $values * @param int $wildcard * @param bool $useEquals * @@ -1614,7 +1643,9 @@ class CRM_Contact_BAO_Query { } /** - * @param $values + * Get the where clause for a single field. + * + * @param array $values */ public function whereClauseSingle(&$values) { // do not process custom fields or prefixed contact ids or component params @@ -1850,8 +1881,7 @@ class CRM_Contact_BAO_Query { } /** - * Given a list of conditions in params generate the required. - * where clause + * Given a list of conditions in params generate the required where clause. * * @return string */ @@ -1880,7 +1910,7 @@ class CRM_Contact_BAO_Query { } if ($this->_customQuery) { - // Added following if condition to avoid the wrong value diplay for 'myaccount' / any UF info. + // Added following if condition to avoid the wrong value display for 'my account' / any UF info. // Hope it wont affect the other part of civicrm.. if it does please remove it. if (!empty($this->_customQuery->_where)) { $this->_where = CRM_Utils_Array::crmArrayMerge($this->_where, $this->_customQuery->_where); @@ -1917,7 +1947,9 @@ class CRM_Contact_BAO_Query { } /** - * @param $values + * Generate where clause for any parameters not already handled. + * + * @param array $values * * @throws Exception */ @@ -1934,7 +1966,7 @@ class CRM_Contact_BAO_Query { $multipleFields = array('url'); - //check if the location type exits for fields + //check if the location type exists for fields $lType = ''; $locType = explode('-', $name); @@ -2645,9 +2677,7 @@ class CRM_Contact_BAO_Query { /** * WHERE / QILL clause for deleted_contacts * - * @param $values - * - * @return void + * @param array $values */ public function deletedContacts($values) { list($_, $_, $value, $grouping, $_) = $values; @@ -2661,8 +2691,6 @@ class CRM_Contact_BAO_Query { * Where / qill clause for contact_type * * @param $values - * - * @return void */ public function contactType(&$values) { list($name, $op, $value, $grouping, $wildcard) = $values; @@ -2728,8 +2756,6 @@ class CRM_Contact_BAO_Query { * Where / qill clause for contact_sub_type * * @param $values - * - * @return void */ public function contactSubType(&$values) { list($name, $op, $value, $grouping, $wildcard) = $values; @@ -2775,8 +2801,6 @@ class CRM_Contact_BAO_Query { * Where / qill clause for groups * * @param $values - * - * @return void */ public function group(&$values) { list($name, $op, $value, $grouping, $wildcard) = $values; @@ -5615,31 +5639,31 @@ AND displayRelType.is_active = 1 * * Qill refers to the query detail visible on the UI. * - * @param $daoName - * @param $fieldName - * @param $fieldValue - * @param $op - * @param array $pseduoExtraParam + * @param string $daoName + * @param string $fieldName + * @param mixed $fieldValue + * @param string $op + * @param array $pseudoExtraParam * * @return array */ - public static function buildQillForFieldValue($daoName = NULL, $fieldName, $fieldValue, $op, $pseduoExtraParam = array()) { + public static function buildQillForFieldValue($daoName = NULL, $fieldName, $fieldValue, $op, $pseudoExtraParam = array()) { $qillOperators = CRM_Core_SelectValues::getSearchBuilderOperators(); if ($fieldName == 'activity_type_id') { - $pseduoOptions = CRM_Core_PseudoConstant::activityType(TRUE, TRUE, FALSE, 'label', TRUE); + $pseudoOptions = CRM_Core_PseudoConstant::activityType(TRUE, TRUE, FALSE, 'label', TRUE); } elseif ($daoName == 'CRM_Event_DAO_Event' && $fieldName == 'id') { - $pseduoOptions = CRM_Event_BAO_Event::getEvents(0, $fieldValue, TRUE, TRUE, TRUE); + $pseudoOptions = CRM_Event_BAO_Event::getEvents(0, $fieldValue, TRUE, TRUE, TRUE); } elseif ($daoName == 'CRM_Contact_DAO_Group' && $fieldName == 'id') { - $pseduoOptions = CRM_Core_PseudoConstant::group(); + $pseudoOptions = CRM_Core_PseudoConstant::group(); } elseif ($fieldName == 'country_id') { - $pseduoOptions = CRM_Core_PseudoConstant::country(); + $pseudoOptions = CRM_Core_PseudoConstant::country(); } elseif ($daoName) { - $pseduoOptions = CRM_Core_PseudoConstant::get($daoName, $fieldName, $pseduoExtraParam = array()); + $pseudoOptions = CRM_Core_PseudoConstant::get($daoName, $fieldName, $pseudoExtraParam = array()); } //API usually have fieldValue format as array(operator => array(values)), @@ -5651,9 +5675,9 @@ AND displayRelType.is_active = 1 if (is_array($fieldValue)) { $qillString = array(); - if (!empty($pseduoOptions)) { + if (!empty($pseudoOptions)) { foreach ((array) $fieldValue as $val) { - $qillString[] = CRM_Utils_Array::value($val, $pseduoOptions, $val); + $qillString[] = CRM_Utils_Array::value($val, $pseudoOptions, $val); } $fieldValue = implode(', ', $qillString); } @@ -5661,8 +5685,8 @@ AND displayRelType.is_active = 1 $fieldValue = implode(', ', $fieldValue); } } - elseif (!empty($pseduoOptions) && array_key_exists($fieldValue, $pseduoOptions)) { - $fieldValue = $pseduoOptions[$fieldValue]; + elseif (!empty($pseudoOptions) && array_key_exists($fieldValue, $pseudoOptions)) { + $fieldValue = $pseudoOptions[$fieldValue]; } return array(CRM_Utils_Array::value($op, $qillOperators, $op), $fieldValue); diff --git a/CRM/Contact/Form/Search/Advanced.php b/CRM/Contact/Form/Search/Advanced.php index 8e9f0678d8..e8d0b4ca73 100644 --- a/CRM/Contact/Form/Search/Advanced.php +++ b/CRM/Contact/Form/Search/Advanced.php @@ -415,6 +415,7 @@ class CRM_Contact_Form_Search_Advanced extends CRM_Contact_Form_Search { * Normalize default values for multiselect plugins. * * @param array $defaults + * * @return array */ public function normalizeDefaultValues(&$defaults) { diff --git a/CRM/Core/BAO/CustomQuery.php b/CRM/Core/BAO/CustomQuery.php index 221cbdf4b6..32042dbfa4 100644 --- a/CRM/Core/BAO/CustomQuery.php +++ b/CRM/Core/BAO/CustomQuery.php @@ -30,8 +30,6 @@ * * @package CRM * @copyright CiviCRM LLC (c) 2004-2015 - * $Id$ - * */ class CRM_Core_BAO_CustomQuery { const PREFIX = 'custom_value_'; @@ -81,7 +79,8 @@ class CRM_Core_BAO_CustomQuery { public $_qill; /** - * The cache to translate the option values into labels. + * @deprecated + * No longer needed due to CRM-17646 refactoring, but still used in some places * * @var array */ @@ -254,9 +253,6 @@ SELECT label, value /** * Generate the select clause and the associated tables. - * for the from clause - * - * @return void */ public function select() { if (empty($this->_fields)) { @@ -318,15 +314,12 @@ SELECT label, value } /** - * Generate the where clause and also the english language. - * equivalent - * - * @return void + * Generate the where clause and also the english language equivalent. */ public function where() { foreach ($this->_ids as $id => $values) { - // Fixed for Isuue CRM 607 + // Fixed for Issue CRM 607 if (CRM_Utils_Array::value($id, $this->_fields) === NULL || !$values ) { diff --git a/CRM/Core/DAO.php b/CRM/Core/DAO.php index 3c5f3294b8..7fcdbbcd21 100644 --- a/CRM/Core/DAO.php +++ b/CRM/Core/DAO.php @@ -30,8 +30,6 @@ * * @package CRM * @copyright CiviCRM LLC (c) 2004-2015 - * $Id$ - * */ require_once 'PEAR.php'; @@ -99,8 +97,6 @@ class CRM_Core_DAO extends DB_DataObject { * * @param string $dsn * The database connection string. - * - * @return void */ public static function init($dsn) { $options = &PEAR::getStaticProperty('DB_DataObject', 'options'); @@ -220,7 +216,7 @@ class CRM_Core_DAO extends DB_DataObject { break; case CRM_Utils_Type::T_TIME: - CRM_Core_Error::fatal('T_TIME shouldnt be used.'); + CRM_Core_Error::fatal("T_TIME shouldn't be used."); //$object->$dbName='000000'; //break; case CRM_Utils_Type::T_CCNUM: @@ -267,11 +263,11 @@ class CRM_Core_DAO extends DB_DataObject { } /** - * Reset the DAO object. DAO is kinda crappy in that there is an unwritten - * rule of one query per DAO. We attempt to get around this crappy restricrion - * by resetting some of DAO's internal fields. Use this with caution + * Reset the DAO object. + * + * DAO is kinda crappy in that there is an unwritten rule of one query per DAO. * - * @return void + * We attempt to get around this crappy restriction by resetting some of DAO's internal fields. Use this with caution */ public function reset() { @@ -330,8 +326,6 @@ class CRM_Core_DAO extends DB_DataObject { * * @param object $factory * The factory application object. - * - * @return void */ public static function setFactory(&$factory) { self::$_factory = &$factory; @@ -341,8 +335,6 @@ class CRM_Core_DAO extends DB_DataObject { * Factory method to instantiate a new object from a table name. * * @param string $table - * - * @return void */ public function factory($table = '') { if (!isset(self::$_factory)) { @@ -355,8 +347,6 @@ class CRM_Core_DAO extends DB_DataObject { /** * Initialization for all DAO objects. Since we access DB_DO programatically * we need to set the links manually. - * - * @return void */ public function initialize() { $this->_connect(); @@ -437,6 +427,8 @@ class CRM_Core_DAO extends DB_DataObject { } /** + * Save DAO object. + * * @return $this */ public function save() { @@ -571,8 +563,6 @@ class CRM_Core_DAO extends DB_DataObject { * The object that we are extracting data from. * @param array $values * (reference ) associative array of name/value pairs. - * - * @return void */ public static function storeValues(&$object, &$values) { $fields = &$object->fields(); @@ -1138,8 +1128,6 @@ FROM civicrm_domain * Name of the dao object. * @param int $contactId * Id of the contact to delete. - * - * @return void */ public static function deleteEntityContact($daoName, $contactId) { $object = new $daoName(); @@ -2252,6 +2240,8 @@ SELECT contact_id } /** + * Get SQL where clause for SQL filter syntax input parameters. + * * SQL version of api function to assign filters to the DAO based on the syntax * $field => array('IN' => array(4,6,9)) * OR @@ -2272,20 +2262,11 @@ SELECT contact_id * * @throws Exception * - * @todo a better solution would be for the query object to apply these filters based on the - * api supported format (but we don't want to risk breakage in alpha stage & query class is scary - * @todo @time of writing only IN & NOT IN are supported for the array style syntax (as test is - * required to extend further & it may be the comments per above should be implemented. It may be - * preferable to not double-banger the return context next refactor of this - but keeping the attention - * in one place has some advantages as we try to extend this format - * * @return NULL|string|array * a string is returned if $returnSanitisedArray is not set, otherwise and Array or NULL * depending on whether it is supported as yet */ public static function createSQLFilter($fieldName, $filter, $type, $alias = NULL, $returnSanitisedArray = FALSE) { - // http://issues.civicrm.org/jira/browse/CRM-9150 - stick with 'simple' operators for now - // support for other syntaxes is discussed in ticket but being put off for now foreach ($filter as $operator => $criteria) { if (in_array($operator, self::acceptedSQLOperators(), TRUE)) { switch ($operator) { @@ -2397,7 +2378,7 @@ SELECT contact_id } // the string is longer than the length and we need a uniq string - // for the same tablename we need the same uniq string everytime + // for the same tablename we need the same uniq string every time // hence we use md5 on the string, which is not random // we'll append 8 characters to the end of the tableName $md5string = substr(md5($string), 0, 8); -- 2.25.1