From 75840aec1bb00b057936df7ad211824001cd5ad2 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 21 Jul 2022 23:51:29 -0700
Subject: [PATCH] (NFC) CRM_Core_Permission - More docblocks
---
CRM/Core/Permission.php | 15 ++++++++++++---
CRM/Core/Permission/Base.php | 6 +++---
2 files changed, 15 insertions(+), 6 deletions(-)
diff --git a/CRM/Core/Permission.php b/CRM/Core/Permission.php
index 0ae7e331637d..a9d085594ef8 100644
--- a/CRM/Core/Permission.php
+++ b/CRM/Core/Permission.php
@@ -53,10 +53,19 @@ class CRM_Core_Permission {
const AUTH_SRC_UNKNOWN = 0, AUTH_SRC_CHECKSUM = 1, AUTH_SRC_SITEKEY = 2, AUTH_SRC_LOGIN = 4;
/**
- * Get the current permission of this user.
+ * Get the maximum permission of the current user with respect to _any_ contact records.
*
- * @return string
- * the permission of the user (edit or view or null)
+ * Note: This appears to be hydrated via `CRM_Core_Permission*::group()`, which appears to run in
+ * many page-views, but I'm not certain that it's guaranteed.
+ *
+ * @return int|string|null
+ * Highest permission held by the current user.
+ * If the user has "edit" rights to at least 1 contact (via permission or ACL),
+ * then CRM_Core_Permission::EDIT.
+ * If the user has "view" rights to at least 1 contact (via permission or ACL),
+ * then CRM_Core_Permission::VIEW.
+ * Otherwise, NULL.
+ * @see \CRM_Core_Permission_Base::group()
*/
public static function getPermission() {
$config = CRM_Core_Config::singleton();
diff --git a/CRM/Core/Permission/Base.php b/CRM/Core/Permission/Base.php
index c0ac7fcf7447..9b1ae5709bbc 100644
--- a/CRM/Core/Permission/Base.php
+++ b/CRM/Core/Permission/Base.php
@@ -75,10 +75,10 @@ public function translatePermission($perm, $nativePrefix, $map) {
}
/**
- * Get the current permission of this user.
+ * Get the maximum permission of the current user with respect to _any_ contact records.
*
- * @return string
- * the permission of the user (edit or view or null)
+ * @return int|string|null
+ * @see \CRM_Core_Permission::getPermission()
*/
public function getPermission() {
$this->group();