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