Merge pull request #15760 from colemanw/iconPicker

[civicrm-core.git] / Civi / Api4 / Generic / AbstractAction.php

diff --git a/Civi/Api4/Generic/AbstractAction.php b/Civi/Api4/Generic/AbstractAction.php
index 41685377186e5643361e0fdca942e431024a8879..310df486e5c4ca14b8573e2d0f0918677167672b 100644 (file)
--- a/Civi/Api4/Generic/AbstractAction.php
+++ b/Civi/Api4/Generic/AbstractAction.php
@@ -26,6 +26,15 @@ use Civi\Api4\Utils\ActionUtil;
 /**
  * Base class for all api actions.
  *
+ * An api Action object stores the parameters of the api call, and defines a _run function to execute the action.
+ *
+ * Every `protected` class var is considered a parameter (unless it starts with an underscore).
+ *
+ * Adding a `protected` var to your Action named e.g. `$thing` will automatically:
+ *  - Provide a getter/setter (via `__call` MagicMethod) named `getThing()` and `setThing()`.
+ *  - Expose the param in the Api Explorer (be sure to add a doc-block as it displays in the help panel).
+ *  - Require a value for the param if you add the "@required" annotation.
+ *
  * @method $this setCheckPermissions(bool $value) Enable/disable permission checks
  * @method bool getCheckPermissions()
  * @method $this setDebug(bool $value) Enable/disable debug output
@@ -75,6 +84,11 @@ abstract class AbstractAction implements \ArrayAccess {
   /**
    * Add debugging info to the api result.
    *
+   * When enabled, the $result->debug will be populated with information about the api call,
+   * including sql queries executed.
+   *
+   * Note: with checkPermissions enabled, debug info will only be returned if the user has "view debug output" permission.
+   *
    * @var bool
    */
   protected $debug = FALSE;
@@ -116,7 +130,7 @@ abstract class AbstractAction implements \ArrayAccess {
    */
   private $_id;
 
-  protected $_debugOutput = [];
+  public $_debugOutput = [];
 
   /**
    * Action constructor.
@@ -213,6 +227,7 @@ abstract class AbstractAction implements \ArrayAccess {
     $kernel = \Civi::service('civi_api_kernel');
     $result = $kernel->runRequest($this);
     if ($this->debug && (!$this->checkPermissions || \CRM_Core_Permission::check('view debug output'))) {
+      $result->debug['actionClass'] = get_class($this);
       $result->debug = array_merge($result->debug, $this->_debugOutput);
     }
     else {
@@ -465,4 +480,25 @@ abstract class AbstractAction implements \ArrayAccess {
     return (bool) trim(\CRM_Core_Smarty::singleton()->fetchWith('string:' . $tpl, $vars));
   }
 
+  /**
+   * When in debug mode, this logs the callback function being used by a Basic*Action class.
+   *
+   * @param callable $callable
+   */
+  protected function addCallbackToDebugOutput($callable) {
+    if ($this->debug && empty($this->_debugOutput['callback'])) {
+      if (is_scalar($callable)) {
+        $this->_debugOutput['callback'] = (string) $callable;
+      }
+      elseif (is_array($callable)) {
+        foreach ($callable as $key => $unit) {
+          $this->_debugOutput['callback'][$key] = is_object($unit) ? get_class($unit) : (string) $unit;
+        }
+      }
+      elseif (is_object($callable)) {
+        $this->_debugOutput['callback'] = get_class($callable);
+      }
+    }
+  }
+
 }