Merge pull request #22454 from braders/phpdoc-types

A whole bunch of phpdoc fixes

CRM/ACL/API.php

@@ -33,7 +33,7 @@ class CRM_ACL_API {
    *
    * @param string $str
    *   The permission to check.
-   * @param int $contactID
+   * @param int|null $contactID
    *   The contactID for whom the check is made.
    *
    * @return bool
@@ -64,7 +64,7 @@ public static function check($str, $contactID = NULL) {
    *   (reference ) add the tables that are needed for the select clause.
    * @param array $whereTables
    *   (reference ) add the tables that are needed for the where clause.
-   * @param int $contactID
+   * @param int|null $contactID
    *   The contactID for whom the check is made.
    * @param bool $onlyDeleted
    *   Whether to include only deleted contacts.
@@ -135,12 +135,12 @@ public static function whereClause(
    *
    * @param int $type
    *   The type of permission needed.
-   * @param int $contactID
+   * @param int|null $contactID
    *   The contactID for whom the check is made.
    *
    * @param string $tableName
-   * @param null $allGroups
-   * @param null $includedGroups
+   * @param array|null $allGroups
+   * @param array|null $includedGroups
    *
    * @return array
    *   the ids of the groups for which the user has permissions
@@ -165,11 +165,11 @@ public static function group(
    * @param int $type
    *   The type of permission needed.
    * @param int $groupID
-   * @param int $contactID
+   * @param int|null $contactID
    *   The contactID for whom the check is made.
    * @param string $tableName
-   * @param null $allGroups
-   * @param null $includedGroups
+   * @param array|null $allGroups
+   * @param array|null $includedGroups
    *
    * @return bool
    */

CRM/ACL/BAO/ACL.php

@@ -83,7 +83,7 @@ protected static function getGroupACLRoles(int $contact_id) {
   /**
    * Get all ACLs owned by a given contact, including domain and group-level.
    *
-   * @param int|null $contact_id
+   * @param int $contact_id
    *   The contact ID.
    *
    * @return array
@@ -185,7 +185,7 @@ public static function setIsActive($id, $is_active) {
   }
 
   /**
-   * @param $str
+   * @param string $str
    * @param int $contactID
    *
    * @return bool
@@ -219,9 +219,9 @@ public static function check($str, $contactID) {
   }
 
   /**
-   * @param $type
-   * @param $tables
-   * @param $whereTables
+   * @param int $type
+   * @param array $tables
+   * @param array $whereTables
    * @param int $contactID
    *
    * @return null|string
@@ -314,8 +314,8 @@ public static function whereClause($type, &$tables, &$whereTables, $contactID =
    * @param int $type
    * @param int $contactID
    * @param string $tableName
-   * @param null $allGroups
-   * @param null $includedGroups
+   * @param array|null $allGroups
+   * @param array|null $includedGroups
    *
    * @return array
    */
@@ -385,7 +385,7 @@ public static function group(
 
   /**
    * @param int $type
-   * @param $operation
+   * @param string $operation
    *
    * @return bool
    */
@@ -456,7 +456,7 @@ public static function self_hook_civicrm_pre(\Civi\Core\Event\PreEvent $event) {
    * @param int $contactID
    * @param string $tableName
    * @param int $type
-   * @param $allGroups
+   * @param array $allGroups
    *
    * @return array
    */

CRM/Activity/BAO/ActivityType.php

@@ -37,7 +37,7 @@ class CRM_Activity_BAO_ActivityType {
   /**
    * Constructor
    *
-   * @param $activity_type_id int This matches up to the option_value 'value' column in the database.
+   * @param int $activity_type_id This matches up to the option_value 'value' column in the database.
    */
   public function __construct($activity_type_id) {
     $this->setActivityType($activity_type_id);
@@ -57,7 +57,7 @@ public function getActivityType() {
    * Look up the key/value pair representing this activity type from the id.
    * Generally called from constructor.
    *
-   * @param $activity_type_id int This matches up to the option_value 'value' column in the database.
+   * @param int $activity_type_id This matches up to the option_value 'value' column in the database.
    */
   public function setActivityType($activity_type_id) {
     if ($activity_type_id && is_numeric($activity_type_id)) {

CRM/Admin/Form.php

@@ -30,7 +30,7 @@ class CRM_Admin_Form extends CRM_Core_Form {
   /**
    * The default values for form fields.
    *
-   * @var int
+   * @var array
    */
   protected $_values;
 

CRM/Admin/Form/Extensions.php

@@ -151,7 +151,7 @@ public function buildQuickForm() {
    *   The input form values.
    * @param array $files
    *   The uploaded files if any.
-   * @param array $self
+   * @param self $self
    *   This object.
    *
    * @return bool|array

CRM/Admin/Form/MessageTemplates.php

@@ -244,7 +244,7 @@ private function checkUserPermission($workflowId) {
    *   The input form values.
    * @param array $files
    *   The uploaded files if any.
-   * @param array $self
+   * @param self $self
    *
    * @return array
    *   array of errors

CRM/Admin/Form/Options.php

@@ -342,7 +342,7 @@ public function buildQuickForm() {
    *   The input form values.
    * @param array $files
    *   The uploaded files if any.
-   * @param array $self
+   * @param self $self
    *   Current form object.
    *
    * @return array

CRM/Admin/Form/PaymentProcessor.php

@@ -295,8 +295,8 @@ public static function formRule($fields) {
   }
 
   /**
-   * @param $fields
-   * @param $errors
+   * @param array $fields
+   * @param array $errors
    * @param null $section
    *
    * @return bool

CRM/Admin/Form/Setting/Localization.php

@@ -230,8 +230,8 @@ public function postProcess() {
   /**
    * Replace available currencies by the ones provided
    *
-   * @param $currencies array of currencies ['USD', 'CAD']
-   * @param $default default currency
+   * @param string[] $currencies array of currencies ['USD', 'CAD']
+   * @param string $default default currency
    */
   public static function updateEnabledCurrencies($currencies, $default) {
 
@@ -339,7 +339,7 @@ public static function onChangeDefaultCurrency($oldCurrency, $newCurrency, $meta
     $currencies = array_keys(CRM_Core_OptionGroup::values('currencies_enabled'));
     if (!in_array($newCurrency, $currencies)) {
       if (empty($currencies)) {
-        $currencies = [$values['defaultCurrency']];
+        $currencies = [$newCurrency];
       }
       else {
         $currencies[] = $newCurrency;

CRM/Admin/Form/Setting/Mail.php

@@ -41,7 +41,7 @@ public function buildQuickForm() {
   }
 
   /**
-   * @param $fields
+   * @param array $fields
    *
    * @return array|bool
    */

CRM/Badge/BAO/Layout.php

@@ -145,7 +145,7 @@ public static function buildLayout(&$params) {
   /**
    * Decode encoded data and return as an array.
    *
-   * @param json $jsonData
+   * @param string $jsonData
    *   Json object.
    *
    * @return array

CRM/Campaign/BAO/Survey.php

@@ -549,8 +549,8 @@ public static function voterActivityDetails($surveyId, $voterIds, $interviewerId
    * @param array $voterIds
    * @param bool $onlyCount
    *
-   * @return array
-   *   An array of survey activity.
+   * @return array|int
+   *   An array of survey activity, or an int if $onlyCount is set to TRUE
    */
   public static function getSurveyActivities(
     $surveyId,

CRM/Contact/BAO/Contact.php

@@ -233,7 +233,7 @@ public static function add(&$params) {
    * @param bool $skipDelete
    *   Unclear parameter, passed to website create
    *
-   * @return CRM_Contact_BAO_Contact|CRM_Core_Error
+   * @return CRM_Contact_BAO_Contact|CRM_Core_Error|NULL
    *   Created or updated contribution object. We are deprecating returning an error in
    *   favour of exceptions
    *
@@ -550,7 +550,7 @@ public static function ensureGreetingParamsAreSet(&$params) {
    * @param bool $includeTypeInReturnParameters
    *   Should type be part of the returned array?
    *
-   * @return array
+   * @return array|null
    *   the displayName and contactImage for this contact
    */
   public static function getDisplayAndImage($id, $includeTypeInReturnParameters = FALSE) {
@@ -1840,16 +1840,16 @@ public static function &makeHierReturnProperties($fields, $contactId = NULL) {
    *
    * $params int     $contactId contact_id
    * $params boolean $isPrimaryExist if true, return primary contact location type otherwise null
-   * $params boolean $skipDefaultPriamry if true, return primary contact location type otherwise null
+   * $params boolean $skipDefaultPrimary if true, return primary contact location type otherwise null
    *
    * @param int $contactId
-   * @param bool $skipDefaultPriamry
+   * @param bool $skipDefaultPrimary
    * @param null $block
    *
-   * @return int
+   * @return int|NULL
    *   $locationType location_type_id
    */
-  public static function getPrimaryLocationType($contactId, $skipDefaultPriamry = FALSE, $block = NULL) {
+  public static function getPrimaryLocationType($contactId, $skipDefaultPrimary = FALSE, $block = NULL) {
     if ($block) {
       $entityBlock = ['contact_id' => $contactId];
       $blocks = CRM_Core_BAO_Location::getValues($entityBlock);
@@ -1891,7 +1891,7 @@ public static function getPrimaryLocationType($contactId, $skipDefaultPriamry =
     if (isset($locationType)) {
       return $locationType;
     }
-    elseif ($skipDefaultPriamry) {
+    elseif ($skipDefaultPrimary) {
       // if there is no primary contact location then return null
       return NULL;
     }
@@ -2765,7 +2765,7 @@ public static function getCountComponent($component, $contactId, $tableName = NU
             $tableName = CRM_Core_DAO::getFieldValue('CRM_Core_DAO_CustomGroup', $custom['1'], 'table_name');
           }
           $queryString = "SELECT count(id) FROM {$tableName} WHERE entity_id = {$contactId}";
-          return CRM_Core_DAO::singleValueQuery($queryString);
+          return (int) CRM_Core_DAO::singleValueQuery($queryString);
         }
     }
   }
@@ -3633,7 +3633,7 @@ public static function isFieldHasLocationType($fieldTitle) {
    * @param array $appendProfiles
    *   Name of profile(s) to append to each link.
    *
-   * @return array
+   * @return array|false
    */
   public static function getEntityRefCreateLinks($appendProfiles = []) {
     // You'd think that "create contacts" would be the permission to check,

CRM/Contact/BAO/Contact/Utils.php

@@ -139,8 +139,8 @@ public static function checkContactType(&$contactIds) {
    * @param string $entityType
    * @param null $hashSize
    *
-   * @return array
-   *   ( $cs, $ts, $live )
+   * @return string
+   *   (Underscore separated: $cs, $ts, $live )
    * @throws \CRM_Core_Exception
    */
   public static function generateChecksum($entityId, $ts = NULL, $live = NULL, $hash = NULL, $entityType = 'contact', $hashSize = NULL) {
@@ -402,7 +402,7 @@ private static function currentEmployerRelatedMembership($contactID, $employerID
       }
     }
 
-    //need to handle related meberships. CRM-3792
+    //need to handle related memberships. CRM-3792
     if ($previousEmpID != $employerID) {
       CRM_Contact_BAO_Relationship::relatedMemberships($contactID, $relationshipParams, $ids, $action);
     }
@@ -455,7 +455,7 @@ public static function clearCurrentEmployer($contactId, $employerId = NULL) {
 
     $dao = CRM_Core_DAO::executeQuery($query);
 
-    // need to handle related meberships. CRM-3792
+    // need to handle related memberships. CRM-3792
     if ($employerId) {
       //1. disable corresponding relationship.
       //2. delete related membership.

CRM/Contact/BAO/Query.php

@@ -4948,7 +4948,7 @@ public static function getGroupByFromSelectColumns($selectClauses, $groupBy = NU
    *
    * @param bool $skipOrderAndLimit
    *
-   * @return CRM_Core_DAO
+   * @return string|null|CRM_Core_DAO
    */
   public function searchQuery(
     $offset = 0, $rowCount = 0, $sort = NULL,

CRM/Contact/Form/Task/Delete.php

@@ -163,7 +163,7 @@ public function buildQuickForm() {
    *   The input form values.
    * @param array $files
    *   The uploaded files if any.
-   * @param object $self
+   * @param self $self
    *   Form object.
    *
    * @return bool|array

CRM/Contact/Form/Task/SMSCommon.php

@@ -274,7 +274,7 @@ public static function buildQuickForm(&$form) {
    * @param array $fields
    *   The input form values.
    * @param array $dontCare
-   * @param array $self
+   * @param self $self
    *   Additional values form 'this'.
    *
    * @return bool|array

CRM/Core/DAO.php

@@ -124,7 +124,7 @@ class CRM_Core_DAO extends DB_DataObject {
   /**
    * Class constructor.
    *
-   * @return \CRM_Core_DAO
+   * @return static
    */
   public function __construct() {
     $this->initialize();

CRM/Core/IDS.php

@@ -226,7 +226,7 @@ public function react(IDS_Report $result) {
   /**
    * This function writes an entry about the intrusion to the database.
    *
-   * @param array $result
+   * @param IDS_Report $result
    * @param int $reaction
    *
    * @return bool

CRM/Profile/Page/Listings.php

@@ -17,7 +17,7 @@
 
 /**
  * This implements the profile page for all contacts. It uses a selector
- * object to do the actual dispay. The fields displayd are controlled by
+ * object to do the actual display. The fields displayed are controlled by
  * the admin.
  */
 class CRM_Profile_Page_Listings extends CRM_Core_Page {

CRM/Report/Form.php

@@ -1115,7 +1115,7 @@ public function setDefaultValues($freeze = TRUE) {
    * @param string $group
    * @param string $grpFieldName
    *
-   * @return bool
+   * @return object|bool
    */
   public function getElementFromGroup($group, $grpFieldName) {
     $eleObj = $this->getElement($group);
@@ -2224,7 +2224,7 @@ public function whereClause(&$field, $op, $value, $min, $max) {
 
   /**
    * Get SQL where clause for contact subtypes
-   * @param string $field
+   * @param array $field Field specifications
    * @param mixed $value
    * @param string $op SQL Operator
    *

CRM/SMS/Provider.php

@@ -88,7 +88,7 @@ abstract public function send($recipients, $header, $message, $dncID = NULL);
    *
    * Child class could override this function to have better control over the message being sent.
    *
-   * @param string $message
+   * @param Mail_mime $message
    * @param int $contactID
    * @param array $contactDetails
    *