api/v3/Extension.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2016                                |
   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   CRM_Extension_System::singleton()->getManager()->install(array($params['key']));
 248
 249   return civicrm_api3_create_success();
 250 }
 251
 252 /**
 253  * Spec function for getfields
 254  * @param $fields
 255  */
 256 function _civicrm_api3_extension_download_spec(&$fields) {
 257   $fields['key'] = array(
 258     'title' => 'Extension Key',
 259     'api.required' => 1,
 260     'type' => CRM_Utils_Type::T_STRING,
 261     'description' => 'Fully qualified name of the extension',
 262   );
 263   $fields['url'] = array(
 264     'title' => 'Download URL',
 265     'type' => CRM_Utils_Type::T_STRING,
 266     'description' => 'Optional as the system can determine the url automatically for public extensions',
 267   );
 268 }
 269
 270 /**
 271  * Download and install an extension.
 272  *
 273  * @param array $params
 274  *   Input parameters.
 275  *   - local: bool, whether to rescan local filesystem (default: TRUE)
 276  *   - remote: bool, whether to rescan remote repository (default: TRUE)
 277  *
 278  * @return array
 279  *   API result
 280  */
 281 function civicrm_api3_extension_refresh($params) {
 282   $system = CRM_Extension_System::singleton(TRUE);
 283
 284   if ($params['local']) {
 285     $system->getManager()->refresh();
 286     $system->getManager()->getStatuses(); // force immediate scan
 287   }
 288
 289   if ($params['remote']) {
 290     if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements)) {
 291       $system->getBrowser()->refresh();
 292       $system->getBrowser()->getExtensions(); // force immediate download
 293     }
 294   }
 295
 296   return civicrm_api3_create_success();
 297 }
 298
 299 /**
 300  * Spec function for getfields
 301  * @param $fields
 302  */
 303 function _civicrm_api3_extension_refresh_spec(&$fields) {
 304   $fields['local'] = array(
 305     'title' => 'Rescan Local',
 306     'api.default' => 1,
 307     'type' => CRM_Utils_Type::T_BOOLEAN,
 308     'description' => 'Whether to rescan the local filesystem (default TRUE)',
 309   );
 310   $fields['remote'] = array(
 311     'title' => 'Rescan Remote',
 312     'api.default' => 1,
 313     'type' => CRM_Utils_Type::T_BOOLEAN,
 314     'description' => 'Whether to rescan the remote repository (default TRUE)',
 315   );
 316 }
 317
 318 /**
 319  * Get a list of available extensions.
 320  *
 321  * @param array $params
 322  *
 323  * @return array
 324  *   API result
 325  */
 326 function civicrm_api3_extension_get($params) {
 327   $statuses = CRM_Extension_System::singleton()->getManager()->getStatuses();
 328   $result = array();
 329   $id = 0;
 330   foreach ($statuses as $key => $status) {
 331     //try {
 332     //  $info = (array) $mapper->keyToInfo($key);
 333     //} catch (CRM_Extension_Exception $e) {
 334     $info = array();
 335     $info['id'] = $id++; // backward compatibility with indexing scheme
 336     $info['key'] = $key;
 337     //}
 338     $info['status'] = $status;
 339     $result[] = $info;
 340   }
 341   return _civicrm_api3_basic_array_get('Extension', $params, $result, 'id', array('id', 'key', 'status'));
 342 }
 343
 344 /**
 345  * Get a list of remotely available extensions.
 346  *
 347  * @param array $params
 348  *
 349  * @return array
 350  *   API result
 351  */
 352 function civicrm_api3_extension_getremote($params) {
 353   $extensions = CRM_Extension_System::singleton()->getBrowser()->getExtensions();
 354   $result = array();
 355   $id = 0;
 356   foreach ($extensions as $key => $obj) {
 357     $info = array();
 358     $info['id'] = $id++; // backward compatibility with indexing scheme
 359     $info = array_merge($info, (array) $obj);
 360     $result[] = $info;
 361   }
 362   return _civicrm_api3_basic_array_get('Extension', $params, $result, 'id', CRM_Utils_Array::value('return', $params, array()));
 363 }
 364
 365 /**
 366  * Determine the list of extension keys.
 367  *
 368  * @param array $params
 369  *   API request params with 'keys'.
 370  *
 371  * @return array
 372  */
 373 function _civicrm_api3_getKeys($params) {
 374   if (is_array($params['keys'])) {
 375     return $params['keys'];
 376   }
 377   if ($params['keys'] == '') {
 378     return array();
 379   }
 380   return explode(API_V3_EXTENSION_DELIMITER, $params['keys']);
 381 }