Civi/Api4/Action/GetActions.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   7  | This work is published under the GNU AGPLv3 license with some      |
   8  | permitted exceptions and without any warranty. For full license    |
   9  | and copyright information, see https://civicrm.org/licensing       |
  10  +--------------------------------------------------------------------+
  11  */
  12
  13 namespace Civi\Api4\Action;
  14
  15 use Civi\API\Exception\NotImplementedException;
  16 use Civi\Api4\Generic\BasicGetAction;
  17 use Civi\Api4\Utils\ReflectionUtils;
  18
  19 /**
  20  * Get all API actions for the $ENTITY entity.
  21  *
  22  * Includes a list of accepted parameters for each action, descriptions and other documentation.
  23  */
  24 class GetActions extends BasicGetAction {
  25
  26   private $_actions = [];
  27
  28   private $_actionsToGet;
  29
  30   protected function getRecords() {
  31     $this->_actionsToGet = $this->_itemsToGet('name');
  32
  33     $entityReflection = new \ReflectionClass('\Civi\Api4\\' . $this->_entityName);
  34     foreach ($entityReflection->getMethods(\ReflectionMethod::IS_STATIC | \ReflectionMethod::IS_PUBLIC) as $method) {
  35       $actionName = $method->getName();
  36       if ($actionName != 'permissions' && $actionName != 'getInfo' && $actionName[0] != '_') {
  37         $this->loadAction($actionName, $method);
  38       }
  39     }
  40     if (!$this->_actionsToGet || count($this->_actionsToGet) > count($this->_actions)) {
  41       // Search for entity-specific actions in extensions
  42       foreach (\CRM_Extension_System::singleton()->getMapper()->getActiveModuleFiles() as $ext) {
  43         $dir = \CRM_Utils_File::addTrailingSlash(dirname($ext['filePath']));
  44         $this->scanDir($dir . 'Civi/Api4/Action/' . $this->_entityName);
  45       }
  46       // Search for entity-specific actions in core
  47       $this->scanDir(\CRM_Utils_File::addTrailingSlash(__DIR__) . $this->_entityName);
  48     }
  49     ksort($this->_actions);
  50     return $this->_actions;
  51   }
  52
  53   /**
  54    * @param $dir
  55    */
  56   private function scanDir($dir) {
  57     if (is_dir($dir)) {
  58       foreach (glob("$dir/*.php") as $file) {
  59         $matches = [];
  60         preg_match('/(\w*)\.php$/', $file, $matches);
  61         $actionName = array_pop($matches);
  62         $actionClass = new \ReflectionClass('\\Civi\\Api4\\Action\\' . $this->_entityName . '\\' . $actionName);
  63         if ($actionClass->isInstantiable() && $actionClass->isSubclassOf('\\Civi\\Api4\\Generic\\AbstractAction')) {
  64           $this->loadAction(lcfirst($actionName));
  65         }
  66       }
  67     }
  68   }
  69
  70   /**
  71    * @param $actionName
  72    * @param \ReflectionMethod $method
  73    */
  74   private function loadAction($actionName, $method = NULL) {
  75     try {
  76       if (!isset($this->_actions[$actionName]) && (!$this->_actionsToGet || in_array($actionName, $this->_actionsToGet))) {
  77         $action = \Civi\API\Request::create($this->getEntityName(), $actionName, ['version' => 4]);
  78         if (is_object($action) && (!$this->checkPermissions || $action->isAuthorized())) {
  79           $this->_actions[$actionName] = ['name' => $actionName];
  80           if ($this->_isFieldSelected('description', 'comment', 'see')) {
  81             $vars = ['entity' => $this->getEntityName(), 'action' => $actionName];
  82             // Docblock from action class
  83             $actionDocs = ReflectionUtils::getCodeDocs($action->reflect(), NULL, $vars);
  84             unset($actionDocs['method']);
  85             // Docblock from action factory function in entity class. This takes precedence since most action classes are generic.
  86             if ($method) {
  87               $methodDocs = ReflectionUtils::getCodeDocs($method, 'Method', $vars);
  88               // Allow method doc to inherit class doc
  89               if (strpos($method->getDocComment(), '@inheritDoc') !== FALSE && !empty($methodDocs['comment']) && !empty($actionDocs['comment'])) {
  90                 $methodDocs['comment'] .= "\n\n" . $actionDocs['comment'];
  91               }
  92               $actionDocs = array_filter($methodDocs) + $actionDocs;
  93             }
  94             $this->_actions[$actionName] += $actionDocs;
  95           }
  96           if ($this->_isFieldSelected('params')) {
  97             $this->_actions[$actionName]['params'] = $action->getParamInfo();
  98             // Language param is only relevant on multilingual sites
  99             $languageLimit = (array) \Civi::settings()->get('languageLimit');
 100             if (count($languageLimit) < 2) {
 101               unset($this->_actions[$actionName]['params']['language']);
 102             }
 103             elseif (isset($this->_actions[$actionName]['params']['language'])) {
 104               $this->_actions[$actionName]['params']['language']['options'] = array_keys($languageLimit);
 105             }
 106           }
 107         }
 108       }
 109     }
 110     catch (NotImplementedException $e) {
 111     }
 112   }
 113
 114   public function fields() {
 115     return [
 116       [
 117         'name' => 'name',
 118         'description' => 'Action name',
 119       ],
 120       [
 121         'name' => 'description',
 122         'description' => 'Description from docblock',
 123       ],
 124       [
 125         'name' => 'comment',
 126         'description' => 'Comments from docblock',
 127       ],
 128       [
 129         'name' => 'see',
 130         'data_type' => 'Array',
 131         'description' => 'Any @see annotations from docblock',
 132       ],
 133       [
 134         'name' => 'params',
 135         'description' => 'List of all accepted parameters',
 136         'data_type' => 'Array',
 137       ],
 138     ];
 139   }
 140
 141 }