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