api/v3/Extension.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2017                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 define('API_V3_EXTENSION_DELIMITER', ',');
  29
  30
  31 /**
  32  * This provides an api interface for CiviCRM extension management.
  33  *
  34  * @package CiviCRM_APIv3
  35  */
  36
  37 /**
  38  * Install an extension.
  39  *
  40  * @param array $params
  41  *   Input parameters.
  42  *    - key: string, eg "com.example.myextension"
  43  *    - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
  44  *
  45  * Using 'keys' should be more performant than making multiple API calls with 'key'
  46  *
  47  * @return array
  48  */
  49 function civicrm_api3_extension_install($params) {
  50   $keys = _civicrm_api3_getKeys($params);
  51   if (!$keys) {
  52     return civicrm_api3_create_success();
  53   }
  54
  55   try {
  56     CRM_Extension_System::singleton()->getManager()->install($keys);
  57   }
  58   catch (CRM_Extension_Exception $e) {
  59     return civicrm_api3_create_error($e->getMessage());
  60   }
  61
  62   return civicrm_api3_create_success();
  63 }
  64
  65 /**
  66  * Spec function for getfields
  67  * @param $fields
  68  */
  69 function _civicrm_api3_extension_install_spec(&$fields) {
  70   $fields['keys'] = array(
  71     'title' => 'Extension Key(s)',
  72     'api.required' => 1,
  73     'api.aliases' => array('key'),
  74     'type' => CRM_Utils_Type::T_STRING,
  75     'description' => 'Fully qualified name of one or more extensions',
  76   );
  77 }
  78
  79 /**
  80  * Upgrade an extension - runs upgrade_N hooks and system.flush.
  81  *
  82  * @return array
  83  *   API result
  84  */
  85 function civicrm_api3_extension_upgrade() {
  86   CRM_Core_Invoke::rebuildMenuAndCaches(TRUE);
  87   $queue = CRM_Extension_Upgrades::createQueue();
  88   $runner = new CRM_Queue_Runner(array(
  89     'title' => 'Extension Upgrades',
  90     'queue' => $queue,
  91     'errorMode' => CRM_Queue_Runner::ERROR_ABORT,
  92   ));
  93
  94   try {
  95     $result = $runner->runAll();
  96   }
  97   catch (CRM_Extension_Exception $e) {
  98     return civicrm_api3_create_error($e->getMessage());
  99   }
 100
 101   if ($result === TRUE) {
 102     return civicrm_api3_create_success();
 103   }
 104   else {
 105     return $result;
 106   }
 107 }
 108
 109 /**
 110  * Enable an extension.
 111  *
 112  * @param array $params
 113  *   Input parameters.
 114  *    - key: string, eg "com.example.myextension"
 115  *    - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
 116  *
 117  * Using 'keys' should be more performant than making multiple API calls with 'key'
 118  *
 119  * @return array
 120  */
 121 function civicrm_api3_extension_enable($params) {
 122   $keys = _civicrm_api3_getKeys($params);
 123   if (count($keys) == 0) {
 124     return civicrm_api3_create_success();
 125   }
 126
 127   CRM_Extension_System::singleton()->getManager()->enable($keys);
 128   return civicrm_api3_create_success();
 129 }
 130
 131 /**
 132  * Spec function for getfields
 133  * @param $fields
 134  */
 135 function _civicrm_api3_extension_enable_spec(&$fields) {
 136   _civicrm_api3_extension_install_spec($fields);
 137 }
 138
 139 /**
 140  * Disable an extension.
 141  *
 142  * @param array $params
 143  *   Input parameters.
 144  *    - key: string, eg "com.example.myextension"
 145  *    - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
 146  *
 147  * Using 'keys' should be more performant than making multiple API calls with 'key'
 148  *
 149  * @return array
 150  */
 151 function civicrm_api3_extension_disable($params) {
 152   $keys = _civicrm_api3_getKeys($params);
 153   if (count($keys) == 0) {
 154     return civicrm_api3_create_success();
 155   }
 156
 157   CRM_Extension_System::singleton()->getManager()->disable($keys);
 158   return civicrm_api3_create_success();
 159 }
 160
 161 /**
 162  * Spec function for getfields
 163  * @param $fields
 164  */
 165 function _civicrm_api3_extension_disable_spec(&$fields) {
 166   _civicrm_api3_extension_install_spec($fields);
 167 }
 168
 169 /**
 170  * Uninstall an extension.
 171  *
 172  * @param array $params
 173  *   Input parameters.
 174  *    - key: string, eg "com.example.myextension"
 175  *    - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
 176  *
 177  * Using 'keys' should be more performant than making multiple API calls with 'key'
 178  *
 179  * @todo: removeFiles as optional param
 180  *
 181  * @return array
 182  */
 183 function civicrm_api3_extension_uninstall($params) {
 184   $keys = _civicrm_api3_getKeys($params);
 185   if (count($keys) == 0) {
 186     return civicrm_api3_create_success();
 187   }
 188
 189   CRM_Extension_System::singleton()->getManager()->uninstall($keys);
 190   return civicrm_api3_create_success();
 191 }
 192
 193 /**
 194  * Spec function for getfields
 195  * @param $fields
 196  */
 197 function _civicrm_api3_extension_uninstall_spec(&$fields) {
 198   _civicrm_api3_extension_install_spec($fields);
 199   //$fields['removeFiles'] = array(
 200   //  'title' => 'Remove files',
 201   //  'description' => 'Whether to remove the source tree. Default FALSE.',
 202   //  'type' => CRM_Utils_Type::T_BOOLEAN,
 203   //);
 204 }
 205
 206 /**
 207  * Download and install an extension.
 208  *
 209  * @param array $params
 210  *   Input parameters.
 211  *   - key: string, eg "com.example.myextension"
 212  *   - url: string eg "http://repo.com/myextension-1.0.zip"
 213  *
 214  * @throws API_Exception
 215  * @return array
 216  *   API result
 217  */
 218 function civicrm_api3_extension_download($params) {
 219   if (!array_key_exists('url', $params)) {
 220     if (!CRM_Extension_System::singleton()->getBrowser()->isEnabled()) {
 221       throw new API_Exception('Automatic downloading is disabled. Try adding parameter "url"');
 222     }
 223     if ($reqs = CRM_Extension_System::singleton()->getBrowser()->checkRequirements()) {
 224       $first = array_shift($reqs);
 225       throw new API_Exception($first['message']);
 226     }
 227     if ($info = CRM_Extension_System::singleton()->getBrowser()->getExtension($params['key'])) {
 228       if ($info->downloadUrl) {
 229         $params['url'] = $info->downloadUrl;
 230       }
 231     }
 232   }
 233
 234   if (!array_key_exists('url', $params)) {
 235     throw new API_Exception('Cannot resolve download url for extension. Try adding parameter "url"');
 236   }
 237
 238   foreach (CRM_Extension_System::singleton()->getDownloader()->checkRequirements() as $requirement) {
 239     return civicrm_api3_create_error($requirement['message']);
 240   }
 241
 242   if (!CRM_Extension_System::singleton()->getDownloader()->download($params['key'], $params['url'])) {
 243     return civicrm_api3_create_error('Download failed - ZIP file is unavailable or malformed');
 244   }
 245   CRM_Extension_System::singleton()->getCache()->flush();
 246   CRM_Extension_System::singleton(TRUE);
 247   if (CRM_Utils_Array::value('install', $params, TRUE)) {
 248     CRM_Extension_System::singleton()->getManager()->install(array($params['key']));
 249   }
 250
 251   return civicrm_api3_create_success();
 252 }
 253
 254 /**
 255  * Spec function for getfields
 256  * @param $fields
 257  */
 258 function _civicrm_api3_extension_download_spec(&$fields) {
 259   $fields['key'] = array(
 260     'title' => 'Extension Key',
 261     'api.required' => 1,
 262     'type' => CRM_Utils_Type::T_STRING,
 263     'description' => 'Fully qualified name of the extension',
 264   );
 265   $fields['url'] = array(
 266     'title' => 'Download URL',
 267     'type' => CRM_Utils_Type::T_STRING,
 268     'description' => 'Optional as the system can determine the url automatically for public extensions',
 269   );
 270   $fields['install'] = array(
 271     'title' => 'Auto-install',
 272     'type' => CRM_Utils_Type::T_STRING,
 273     'description' => 'Automatically install the downloaded extension',
 274     'api.default' => TRUE,
 275   );
 276 }
 277
 278 /**
 279  * Download and install an extension.
 280  *
 281  * @param array $params
 282  *   Input parameters.
 283  *   - local: bool, whether to rescan local filesystem (default: TRUE)
 284  *   - remote: bool, whether to rescan remote repository (default: TRUE)
 285  *
 286  * @return array
 287  *   API result
 288  */
 289 function civicrm_api3_extension_refresh($params) {
 290   $system = CRM_Extension_System::singleton(TRUE);
 291
 292   if ($params['local']) {
 293     $system->getManager()->refresh();
 294     $system->getManager()->getStatuses(); // force immediate scan
 295   }
 296
 297   if ($params['remote']) {
 298     if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements)) {
 299       $system->getBrowser()->refresh();
 300       $system->getBrowser()->getExtensions(); // force immediate download
 301     }
 302   }
 303
 304   return civicrm_api3_create_success();
 305 }
 306
 307 /**
 308  * Spec function for getfields
 309  * @param $fields
 310  */
 311 function _civicrm_api3_extension_refresh_spec(&$fields) {
 312   $fields['local'] = array(
 313     'title' => 'Rescan Local',
 314     'api.default' => 1,
 315     'type' => CRM_Utils_Type::T_BOOLEAN,
 316     'description' => 'Whether to rescan the local filesystem (default TRUE)',
 317   );
 318   $fields['remote'] = array(
 319     'title' => 'Rescan Remote',
 320     'api.default' => 1,
 321     'type' => CRM_Utils_Type::T_BOOLEAN,
 322     'description' => 'Whether to rescan the remote repository (default TRUE)',
 323   );
 324 }
 325
 326 /**
 327  * Get a list of available extensions.
 328  *
 329  * @param array $params
 330  *
 331  * @return array
 332  *   API result
 333  */
 334 function civicrm_api3_extension_get($params) {
 335   $statuses = CRM_Extension_System::singleton()->getManager()->getStatuses();
 336   $mapper = CRM_Extension_System::singleton()->getMapper();
 337   $result = array();
 338   $id = 0;
 339   foreach ($statuses as $key => $status) {
 340     try {
 341       $obj = $mapper->keyToInfo($key);
 342     }
 343     catch (CRM_Extension_Exception $ex) {
 344       CRM_Core_Session::setStatus(ts('Failed to read extension (%1). Please refresh the extension list.', array(1 => $key)));
 345       continue;
 346     }
 347     $info = CRM_Extension_System::createExtendedInfo($obj);
 348     $info['id'] = $id++; // backward compatibility with indexing scheme
 349     $result[] = $info;
 350   }
 351   return _civicrm_api3_basic_array_get('Extension', $params, $result, 'id', array());
 352 }
 353
 354 /**
 355  * Get a list of remotely available extensions.
 356  *
 357  * @param array $params
 358  *
 359  * @return array
 360  *   API result
 361  */
 362 function civicrm_api3_extension_getremote($params) {
 363   $extensions = CRM_Extension_System::singleton()->getBrowser()->getExtensions();
 364   $result = array();
 365   $id = 0;
 366   foreach ($extensions as $key => $obj) {
 367     $info = array();
 368     $info['id'] = $id++; // backward compatibility with indexing scheme
 369     $info = array_merge($info, (array) $obj);
 370     $result[] = $info;
 371   }
 372   return _civicrm_api3_basic_array_get('Extension', $params, $result, 'id', CRM_Utils_Array::value('return', $params, array()));
 373 }
 374
 375 /**
 376  * Determine the list of extension keys.
 377  *
 378  * @param array $params
 379  *   API request params with 'keys'.
 380  *
 381  * @return array
 382  */
 383 function _civicrm_api3_getKeys($params) {
 384   if (is_array($params['keys'])) {
 385     return $params['keys'];
 386   }
 387   if ($params['keys'] == '') {
 388     return array();
 389   }
 390   return explode(API_V3_EXTENSION_DELIMITER, $params['keys']);
 391 }