From 26a700db1f6337a878711eee776c4c56a3d96c15 Mon Sep 17 00:00:00 2001
From: Coleman Watts <coleman@civicrm.org>
Date: Fri, 27 Mar 2015 14:10:03 -0400
Subject: [PATCH] CRM-16178 - Add api.getfield method

---
 api/v3/Generic.php                      | 71 +++++++++++++++++++++++--
 api/v3/utils.php                        |  3 ++
 templates/CRM/Admin/Page/APIExplorer.js |  2 +-
 3 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/api/v3/Generic.php b/api/v3/Generic.php
index 400c4d7ea3..703c23ca7c 100644
--- a/api/v3/Generic.php
+++ b/api/v3/Generic.php
@@ -48,10 +48,13 @@
  *   - function: callback (mixed)
  *   - params: array, varies
  *
+ * @param bool $unique
+ *   Determines whether to key by unique field names (only affects get-type) actions
+ *
  * @return array
  *   API success object
  */
-function civicrm_api3_generic_getfields($apiRequest) {
+function civicrm_api3_generic_getfields($apiRequest, $unique = TRUE) {
   static $results = array();
   if ((CRM_Utils_Array::value('cache_clear', $apiRequest['params']))) {
     $results = array();
@@ -82,8 +85,6 @@ function civicrm_api3_generic_getfields($apiRequest) {
   if (!$action || $action == 'getvalue' || $action == 'getcount') {
     $action = 'get';
   }
-  // determines whether to use unique field names - see comment block above
-  $unique = TRUE;
   // If no options, return results from cache
   if (!$apiRequest['params']['options'] && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
     && isset($action, $results[$entity . $subentity][$sequential])) {
@@ -203,6 +204,70 @@ function civicrm_api3_generic_getfields($apiRequest) {
   return $results[$entity][$action][$sequential];
 }
 
+/**
+ * Get metadata for a field
+ *
+ * @param array $apiRequest
+ *
+ * @return array
+ *   API success object
+ */
+function civicrm_api3_generic_getfield($apiRequest) {
+  $params = $apiRequest['params'];
+  $sequential = !empty($params['sequential']);
+  $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $params['name'], $params['action']);
+  if (!$fieldName) {
+    return civicrm_api3_create_error("The field '{$params['name']}' doesn't exist.");
+  }
+  // Turn off sequential to make the field easier to find
+  $apiRequest['params']['sequential'] = 0;
+  if (!empty($params['options']['get_options'])) {
+    $apiRequest['params']['options']['get_options'] = $fieldName;
+  }
+  if (isset($params['context'])) {
+    $apiRequest['params']['options']['get_options_context'] = $params['context'];
+  }
+  $result = civicrm_api3_generic_getfields($apiRequest, FALSE);
+  $result = $result['values'][$fieldName];
+  // Fix sequential options since we forced it off
+  if ($sequential && !empty($result['options'])) {
+    $result['options'] = CRM_Utils_Array::makeNonAssociative($result['options']);
+  }
+  return civicrm_api3_create_success($result, $apiRequest['params'], $apiRequest['entity'], 'getfield');
+}
+
+
+function _civicrm_api3_generic_getfield_spec(&$params, $apiRequest) {
+  $params = array(
+    'name' => array(
+      'title' => 'Field name',
+      'description' => 'Name or alias of field to lookup',
+      'api.required' => 1,
+      'type' => CRM_Utils_Type::T_STRING,
+    ),
+    'action' => array(
+      'title' => 'API Action',
+      'api.required' => 1,
+      'type' => CRM_Utils_Type::T_STRING,
+      'api.aliases' => array('api_action'),
+    ),
+    'context' => array(
+      'title' => 'Context',
+      'description' => 'Context passed to getoptions. Only relevant if options.get_options is set.',
+      'type' => CRM_Utils_Type::T_STRING,
+      'options' => CRM_Core_DAO::buildOptionsContext(),
+    ),
+  );
+  // Add available options to these params if requested
+  if (array_intersect(array('all', 'action'), $apiRequest['params']['options']['get_options'])) {
+    $actions = civicrm_api3($apiRequest['entity'], 'getactions');
+    $actions = array_combine($actions['values'], $actions['values']);
+    // Let's not go meta-crazy
+    CRM_Utils_Array::remove($actions, 'getactions', 'getoptions', 'getfields', 'getfield', 'getcount', 'getrefcount', 'getsingle', 'getlist', 'getvalue', 'setvalue', 'update');
+    $params['action']['options'] = $actions;
+  }
+}
+
 /**
  * API return function to reformat results as count.
  *
diff --git a/api/v3/utils.php b/api/v3/utils.php
index 9cc7f0e2e4..b616b0ff31 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -2186,6 +2186,9 @@ function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldN
  *   fieldName or FALSE if the field does not exist
  */
 function _civicrm_api3_api_resolve_alias($entity, $fieldName, $action = 'create') {
+  if (!$fieldName) {
+    return FALSE;
+  }
   if (strpos($fieldName, 'custom_') === 0 && is_numeric($fieldName[7])) {
     return $fieldName;
   }
diff --git a/templates/CRM/Admin/Page/APIExplorer.js b/templates/CRM/Admin/Page/APIExplorer.js
index e5d1970e58..547b2b80a1 100644
--- a/templates/CRM/Admin/Page/APIExplorer.js
+++ b/templates/CRM/Admin/Page/APIExplorer.js
@@ -24,7 +24,7 @@
     NO_OPERATORS = ['create', 'update', 'delete', 'setvalue', 'getoptions', 'getactions', 'getfields'],
 
     // Actions that don't support multiple values
-    NO_MULTI = ['delete', 'getoptions', 'getactions', 'getfields', 'setvalue'],
+    NO_MULTI = ['delete', 'getoptions', 'getactions', 'getfields',  'getfield', 'setvalue'],
 
     // Operators with special properties
     BOOL = ['IS NULL', 'IS NOT NULL'],
-- 
2.25.1