api/v3/Extension.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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 api exposes CiviCRM extension.
  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: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
  44  *   Using 'keys' should be more performant than making multiple API calls with 'key'.
  45  *
  46  * @return array
  47  *   API result
  48  */
  49 function civicrm_api3_extension_install($params) {
  50   $keys = _civicrm_api3_getKeys($params);
  51   if (count($keys) == 0) {
  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  * Upgrade an extension - runs upgrade_N hooks and system.flush.
  67  *
  68  * @return array
  69  *   API result
  70  */
  71 function civicrm_api3_extension_upgrade() {
  72   CRM_Core_Invoke::rebuildMenuAndCaches(TRUE);
  73   $queue = CRM_Extension_Upgrades::createQueue();
  74   $runner = new CRM_Queue_Runner(array(
  75     'title' => 'Extension Upgrades',
  76     'queue' => $queue,
  77     'errorMode' => CRM_Queue_Runner::ERROR_ABORT,
  78   ));
  79
  80   try {
  81     $result = $runner->runAll();
  82   }
  83   catch (CRM_Extension_Exception $e) {
  84     return civicrm_api3_create_error($e->getMessage());
  85   }
  86
  87   if ($result === TRUE) {
  88     return civicrm_api3_create_success();
  89   }
  90   else {
  91     return $result;
  92   }
  93 }
  94
  95 /**
  96  * Enable an extension.
  97  *
  98  * @param array $params
  99  *   Input parameters.
 100  *                          - key: string, eg "com.example.myextension"
 101  *                          - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
 102  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 103  *
 104  * @return array
 105  *   API result
 106  */
 107 function civicrm_api3_extension_enable($params) {
 108   $keys = _civicrm_api3_getKeys($params);
 109   if (count($keys) == 0) {
 110     return civicrm_api3_create_success();
 111   }
 112
 113   CRM_Extension_System::singleton()->getManager()->enable($keys);
 114   return civicrm_api3_create_success();
 115 }
 116
 117 /**
 118  * Disable an extension.
 119  *
 120  * @param array $params
 121  *   Input parameters.
 122  *                          - key: string, eg "com.example.myextension"
 123  *                          - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
 124  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 125  *
 126  * @return array
 127  *   API result
 128  */
 129 function civicrm_api3_extension_disable($params) {
 130   $keys = _civicrm_api3_getKeys($params);
 131   if (count($keys) == 0) {
 132     return civicrm_api3_create_success();
 133   }
 134
 135   CRM_Extension_System::singleton()->getManager()->disable($keys);
 136   return civicrm_api3_create_success();
 137 }
 138
 139 /**
 140  * Uninstall 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  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 147  *                          - removeFiles: bool, whether to remove source tree; default: FALSE
 148  *
 149  * @return array
 150  *   API result
 151  */
 152 function civicrm_api3_extension_uninstall($params) {
 153   $keys = _civicrm_api3_getKeys($params);
 154   if (count($keys) == 0) {
 155     return civicrm_api3_create_success();
 156   }
 157
 158   // TODO // $removeFiles = CRM_Utils_Array::value('removeFiles', $params, FALSE);
 159   CRM_Extension_System::singleton()->getManager()->uninstall($keys);
 160   return civicrm_api3_create_success();
 161 }
 162
 163 /**
 164  * Download and install an extension.
 165  *
 166  * @param array $params
 167  *   Input parameters.
 168  *                          - key: string, eg "com.example.myextension"
 169  *                          - url: string eg "http://repo.com/myextension-1.0.zip"
 170  *
 171  * @throws API_Exception
 172  * @return array
 173  *   API result
 174  */
 175 function civicrm_api3_extension_download($params) {
 176   if (!array_key_exists('key', $params)) {
 177     throw new API_Exception('Missing required parameter: key');
 178   }
 179
 180   if (!array_key_exists('url', $params)) {
 181     if (!CRM_Extension_System::singleton()->getBrowser()->isEnabled()) {
 182       throw new API_Exception('Automatic downloading is diabled. Try adding parameter "url"');
 183     }
 184     if ($reqs = CRM_Extension_System::singleton()->getBrowser()->checkRequirements()) {
 185       $first = array_shift($reqs);
 186       throw new API_Exception($first['message']);
 187     }
 188     if ($info = CRM_Extension_System::singleton()->getBrowser()->getExtension($params['key'])) {
 189       if ($info->downloadUrl) {
 190         $params['url'] = $info->downloadUrl;
 191       }
 192     }
 193   }
 194
 195   if (!array_key_exists('url', $params)) {
 196     throw new API_Exception('Cannot resolve download url for extension. Try adding parameter "url"');
 197   }
 198
 199   foreach (CRM_Extension_System::singleton()->getDownloader()->checkRequirements() as $requirement) {
 200     return civicrm_api3_create_error($requirement['message']);
 201   }
 202
 203   if (!CRM_Extension_System::singleton()->getDownloader()->download($params['key'], $params['url'])) {
 204     return civicrm_api3_create_error('Download failed - ZIP file is unavailable or malformed');
 205   }
 206   CRM_Extension_System::singleton()->getCache()->flush();
 207   CRM_Extension_System::singleton(TRUE);
 208   CRM_Extension_System::singleton()->getManager()->install(array($params['key']));
 209
 210   return civicrm_api3_create_success();
 211 }
 212
 213 /**
 214  * Download and install an extension.
 215  *
 216  * @param array $params
 217  *   Input parameters.
 218  *                          - local: bool, whether to rescan local filesystem (default: TRUE)
 219  *                          - remote: bool, whether to rescan remote repository (default: TRUE)
 220  *
 221  * @return array
 222  *   API result
 223  */
 224 function civicrm_api3_extension_refresh($params) {
 225   $defaults = array('local' => TRUE, 'remote' => TRUE);
 226   $params = array_merge($defaults, $params);
 227
 228   $system = CRM_Extension_System::singleton(TRUE);
 229
 230   if ($params['local']) {
 231     $system->getManager()->refresh();
 232     $system->getManager()->getStatuses(); // force immediate scan
 233   }
 234
 235   if ($params['remote']) {
 236     if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements)) {
 237       $system->getBrowser()->refresh();
 238       $system->getBrowser()->getExtensions(); // force immediate download
 239     }
 240   }
 241
 242   return civicrm_api3_create_success();
 243 }
 244
 245 /**
 246  * Get a list of available extensions.
 247  *
 248  * @param array $params
 249  *
 250  * @return array
 251  *   API result
 252  */
 253 function civicrm_api3_extension_get($params) {
 254   $statuses = CRM_Extension_System::singleton()->getManager()->getStatuses();
 255   $mapper = CRM_Extension_System::singleton()->getMapper();
 256   $result = array();
 257   foreach ($statuses as $key => $status) {
 258     //try {
 259     //  $info = (array) $mapper->keyToInfo($key);
 260     //} catch (CRM_Extension_Exception $e) {
 261     $info = array();
 262     $info['key'] = $key;
 263     //}
 264     $info['status'] = $status;
 265     $result[] = $info;
 266   }
 267   return civicrm_api3_create_success($result);
 268 }
 269
 270 /**
 271  * Determine the list of extension keys.
 272  *
 273  * @param array $params
 274  *   API request params with 'key' or 'keys'.
 275  *
 276  * @return array
 277  *   Array of extension keys
 278  * @throws API_Exception
 279  */
 280 function _civicrm_api3_getKeys($params) {
 281   if (array_key_exists('keys', $params) && is_array($params['keys'])) {
 282     return $params['keys'];
 283   }
 284   elseif (array_key_exists('keys', $params) && is_string($params['keys'])) {
 285     if ($params['keys'] == '') {
 286       return array();
 287     }
 288     else {
 289       return explode(API_V3_EXTENSION_DELIMITER, $params['keys']);
 290     }
 291   }
 292   elseif (array_key_exists('key', $params)) {
 293     return array($params['key']);
 294   }
 295   else {
 296     throw new API_Exception('Missing required parameter: key or keys');
 297   }
 298 }