Civi/API/Provider/MagicFunctionProvider.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 namespace Civi\API\Provider;
  13
  14 use Civi\API\Events;
  15 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  16
  17 /**
  18  * This class manages the loading of API's using strict file+function naming
  19  * conventions.
  20  */
  21 class MagicFunctionProvider implements EventSubscriberInterface, ProviderInterface {
  22
  23   /**
  24    * @return array
  25    */
  26   public static function getSubscribedEvents() {
  27     return [
  28       Events::RESOLVE => [
  29         ['onApiResolve', Events::W_MIDDLE],
  30       ],
  31     ];
  32   }
  33
  34   /**
  35    * @var array (string $cachekey => array('function' => string, 'is_generic' => bool))
  36    */
  37   private $cache;
  38
  39   /**
  40    */
  41   public function __construct() {
  42     $this->cache = [];
  43   }
  44
  45   /**
  46    * @param \Civi\API\Event\ResolveEvent $event
  47    *   API resolution event.
  48    */
  49   public function onApiResolve(\Civi\API\Event\ResolveEvent $event) {
  50     $apiRequest = $event->getApiRequest();
  51     $resolved = $this->resolve($apiRequest);
  52     if ($resolved['function']) {
  53       $apiRequest += $resolved;
  54       $event->setApiRequest($apiRequest);
  55       $event->setApiProvider($this);
  56       $event->stopPropagation();
  57     }
  58   }
  59
  60   /**
  61    * @inheritDoc
  62    * @param array $apiRequest
  63    * @return array
  64    */
  65   public function invoke($apiRequest) {
  66     $function = $apiRequest['function'];
  67     if ($apiRequest['function'] && $apiRequest['is_generic']) {
  68       // Unlike normal API implementations, generic implementations require explicit
  69       // knowledge of the entity and action (as well as $params). Bundle up these bits
  70       // into a convenient data structure.
  71       if ($apiRequest['action'] === 'getsingle') {
  72         // strip any api nested parts here as otherwise chaining may happen twice
  73         // see https://lab.civicrm.org/dev/core/issues/643
  74         // testCreateBAODefaults fails without this.
  75         foreach ($apiRequest['params'] as $key => $param) {
  76           if ($key !== 'api.has_parent' && substr($key, 0, 4) === 'api.' || substr($key, 0, 4) === 'api_') {
  77             unset($apiRequest['params'][$key]);
  78           }
  79         }
  80       }
  81       $result = $function($apiRequest);
  82
  83     }
  84     elseif ($apiRequest['function'] && !$apiRequest['is_generic']) {
  85       $result = $function($apiRequest['params']);
  86     }
  87     return $result;
  88   }
  89
  90   /**
  91    * @inheritDoc
  92    * @param int $version
  93    * @return array
  94    */
  95   public function getEntityNames($version) {
  96     $entities = [];
  97     $include_dirs = array_unique(explode(PATH_SEPARATOR, get_include_path()));
  98     #$include_dirs = array(dirname(__FILE__). '/../../');
  99     foreach ($include_dirs as $include_dir) {
 100       $api_dir = implode(DIRECTORY_SEPARATOR,
 101         [$include_dir, 'api', 'v' . $version]);
 102       if (!is_dir($api_dir)) {
 103         continue;
 104       }
 105       $iterator = new \DirectoryIterator($api_dir);
 106       foreach ($iterator as $fileinfo) {
 107         $file = $fileinfo->getFilename();
 108
 109         // Check for entities with a master file ("api/v3/MyEntity.php")
 110         $parts = explode(".", $file);
 111         if (end($parts) == "php" && $file != "utils.php" && !preg_match('/Tests?.php$/', $file)) {
 112           // without the ".php"
 113           $entities[] = substr($file, 0, -4);
 114         }
 115
 116         // Check for entities with standalone action files (eg "api/v3/MyEntity/MyAction.php").
 117         $action_dir = $api_dir . DIRECTORY_SEPARATOR . $file;
 118         if (preg_match('/^[A-Z][A-Za-z0-9]*$/', $file) && is_dir($action_dir)) {
 119           if (count(glob("$action_dir/[A-Z]*.php")) > 0) {
 120             $entities[] = $file;
 121           }
 122         }
 123       }
 124     }
 125     $entities = array_diff($entities, ['Generic']);
 126     $entities = array_unique($entities);
 127     sort($entities);
 128
 129     return $entities;
 130   }
 131
 132   /**
 133    * @inheritDoc
 134    * @param int $version
 135    * @param string $entity
 136    * @return array
 137    */
 138   public function getActionNames($version, $entity) {
 139     $entity = _civicrm_api_get_camel_name($entity);
 140     $entities = $this->getEntityNames($version);
 141     if (!in_array($entity, $entities)) {
 142       return [];
 143     }
 144     $this->loadEntity($entity, $version);
 145
 146     $functions = get_defined_functions();
 147     $actions = [];
 148     $prefix = 'civicrm_api' . $version . '_' . _civicrm_api_get_entity_name_from_camel($entity) . '_';
 149     $prefixGeneric = 'civicrm_api' . $version . '_generic_';
 150     foreach ($functions['user'] as $fct) {
 151       if (strpos($fct, $prefix) === 0) {
 152         $actions[] = substr($fct, strlen($prefix));
 153       }
 154       elseif (strpos($fct, $prefixGeneric) === 0) {
 155         $actions[] = substr($fct, strlen($prefixGeneric));
 156       }
 157     }
 158     return $actions;
 159   }
 160
 161   /**
 162    * Look up the implementation for a given API request.
 163    *
 164    * @param array $apiRequest
 165    *   Array with keys:
 166    *   - entity: string, required.
 167    *   - action: string, required.
 168    *   - params: array.
 169    *   - version: scalar, required.
 170    *
 171    * @return array
 172    *   Array with keys:
 173    *   - function: callback (mixed)
 174    *   - is_generic: boolean
 175    */
 176   protected function resolve($apiRequest) {
 177     $cachekey = strtolower($apiRequest['entity']) . ':' . strtolower($apiRequest['action']) . ':' . $apiRequest['version'];
 178     if (isset($this->cache[$cachekey])) {
 179       return $this->cache[$cachekey];
 180     }
 181
 182     $camelName = _civicrm_api_get_camel_name($apiRequest['entity'], $apiRequest['version']);
 183     $actionCamelName = _civicrm_api_get_camel_name($apiRequest['action']);
 184
 185     // Determine if there is an entity-specific implementation of the action
 186     $stdFunction = $this->getFunctionName($apiRequest['entity'], $apiRequest['action'], $apiRequest['version']);
 187     if (function_exists($stdFunction)) {
 188       // someone already loaded the appropriate file
 189       // FIXME: This has the affect of masking bugs in load order; this is
 190       // included to provide bug-compatibility.
 191       $this->cache[$cachekey] = ['function' => $stdFunction, 'is_generic' => FALSE];
 192       return $this->cache[$cachekey];
 193     }
 194
 195     $stdFiles = [
 196       // By convention, the $camelName.php is more likely to contain the
 197       // function, so test it first
 198       'api/v' . $apiRequest['version'] . '/' . $camelName . '.php',
 199       'api/v' . $apiRequest['version'] . '/' . $camelName . '/' . $actionCamelName . '.php',
 200     ];
 201     foreach ($stdFiles as $stdFile) {
 202       if (\CRM_Utils_File::isIncludable($stdFile)) {
 203         require_once $stdFile;
 204         if (function_exists($stdFunction)) {
 205           $this->cache[$cachekey] = ['function' => $stdFunction, 'is_generic' => FALSE];
 206           return $this->cache[$cachekey];
 207         }
 208       }
 209     }
 210
 211     // Determine if there is a generic implementation of the action
 212     require_once 'api/v3/Generic.php';
 213     # $genericFunction = 'civicrm_api3_generic_' . $apiRequest['action'];
 214     $genericFunction = $this->getFunctionName('generic', $apiRequest['action'], $apiRequest['version']);
 215     $genericFiles = [
 216       // By convention, the Generic.php is more likely to contain the
 217       // function, so test it first
 218       'api/v' . $apiRequest['version'] . '/Generic.php',
 219       'api/v' . $apiRequest['version'] . '/Generic/' . $actionCamelName . '.php',
 220     ];
 221     foreach ($genericFiles as $genericFile) {
 222       if (\CRM_Utils_File::isIncludable($genericFile)) {
 223         require_once $genericFile;
 224         if (function_exists($genericFunction)) {
 225           $this->cache[$cachekey] = ['function' => $genericFunction, 'is_generic' => TRUE];
 226           return $this->cache[$cachekey];
 227         }
 228       }
 229     }
 230
 231     $this->cache[$cachekey] = ['function' => FALSE, 'is_generic' => FALSE];
 232     return $this->cache[$cachekey];
 233   }
 234
 235   /**
 236    * Determine the function name for a given API request.
 237    *
 238    * @param string $entity
 239    *   API entity name.
 240    * @param string $action
 241    *   API action name.
 242    * @param int $version
 243    *   API version.
 244    *
 245    * @return string
 246    */
 247   protected function getFunctionName($entity, $action, $version) {
 248     $entity = _civicrm_api_get_entity_name_from_camel($entity);
 249     return 'civicrm_api' . $version . '_' . $entity . '_' . $action;
 250   }
 251
 252   /**
 253    * Load/require all files related to an entity.
 254    *
 255    * This should not normally be called because it's does a file-system scan; it's
 256    * only appropriate when introspection is really required (eg for "getActions").
 257    *
 258    * @param string $entity
 259    *   API entity name.
 260    * @param int $version
 261    *   API version.
 262    */
 263   protected function loadEntity($entity, $version) {
 264     $camelName = _civicrm_api_get_camel_name($entity, $version);
 265
 266     // Check for master entity file; to match _civicrm_api_resolve(), only load the first one
 267     $stdFile = 'api/v' . $version . '/' . $camelName . '.php';
 268     if (\CRM_Utils_File::isIncludable($stdFile)) {
 269       require_once $stdFile;
 270     }
 271
 272     // Check for standalone action files; to match _civicrm_api_resolve(), only load the first one
 273     // array($relativeFilePath => TRUE)
 274     $loaded_files = [];
 275     $include_dirs = array_unique(explode(PATH_SEPARATOR, get_include_path()));
 276     foreach ($include_dirs as $include_dir) {
 277       foreach ([$camelName, 'Generic'] as $name) {
 278         $action_dir = implode(DIRECTORY_SEPARATOR,
 279           [$include_dir, 'api', "v${version}", $name]);
 280         if (!is_dir($action_dir)) {
 281           continue;
 282         }
 283
 284         $iterator = new \DirectoryIterator($action_dir);
 285         foreach ($iterator as $fileinfo) {
 286           $file = $fileinfo->getFilename();
 287           if (array_key_exists($file, $loaded_files)) {
 288             // action provided by an earlier item on include_path
 289             continue;
 290           }
 291
 292           $parts = explode(".", $file);
 293           if (end($parts) == "php" && !preg_match('/Tests?\.php$/', $file)) {
 294             require_once $action_dir . DIRECTORY_SEPARATOR . $file;
 295             $loaded_files[$file] = TRUE;
 296           }
 297         }
 298       }
 299     }
 300   }
 301
 302 }