api/v3/Extension.php

   1 <?php
   2
   3 define('API_V3_EXTENSION_DELIMITER', ',');
   4
   5 /*
   6  +--------------------------------------------------------------------+
   7  | CiviCRM version 4.5                                                |
   8  +--------------------------------------------------------------------+
   9  | Copyright CiviCRM LLC (c) 2004-2014                                |
  10  +--------------------------------------------------------------------+
  11  | This file is a part of CiviCRM.                                    |
  12  |                                                                    |
  13  | CiviCRM is free software; you can copy, modify, and distribute it  |
  14  | under the terms of the GNU Affero General Public License           |
  15  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  16  |                                                                    |
  17  | CiviCRM is distributed in the hope that it will be useful, but     |
  18  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  19  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  20  | See the GNU Affero General Public License for more details.        |
  21  |                                                                    |
  22  | You should have received a copy of the GNU Affero General Public   |
  23  | License and the CiviCRM Licensing Exception along                  |
  24  | with this program; if not, contact CiviCRM LLC                     |
  25  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  26  | GNU Affero General Public License or the licensing of CiviCRM,     |
  27  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  28  +--------------------------------------------------------------------+
  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 input parameters
  46  *                          - key: string, eg "com.example.myextension"
  47  *                          - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
  48  *                            using 'keys' should be more performant than making multiple API calls with 'key'
  49  *
  50  * @return array API result
  51  * @static void
  52  * @access public
  53  * @example ExtensionInstall.php
  54  *
  55  */
  56 function civicrm_api3_extension_install($params) {
  57   $keys = _civicrm_api3_getKeys($params);
  58   if (count($keys) == 0) {
  59     return civicrm_api3_create_success();
  60   }
  61
  62   try {
  63     CRM_Extension_System::singleton()->getManager()->install($keys);
  64   } catch (CRM_Extension_Exception $e) {
  65     return civicrm_api3_create_error($e->getMessage());
  66   }
  67
  68   return civicrm_api3_create_success();
  69 }
  70
  71 /**
  72  * Upgrade an extension - runs upgrade_N hooks and system.flush
  73  *
  74  * @return array API result
  75  * @static void
  76  * @access public
  77  *
  78  */
  79 function civicrm_api3_extension_upgrade() {
  80   CRM_Core_Invoke::rebuildMenuAndCaches(TRUE);
  81   $queue = CRM_Extension_Upgrades::createQueue();
  82   $runner = new CRM_Queue_Runner(array(
  83     'title' => 'Extension Upgrades',
  84     'queue' => $queue,
  85     'errorMode' => CRM_Queue_Runner::ERROR_ABORT,
  86   ));
  87
  88   try {
  89     $result = $runner->runAll();
  90   } catch (CRM_Extension_Exception $e) {
  91     return civicrm_api3_create_error($e->getMessage());
  92   }
  93
  94   if ($result === TRUE) {
  95     return civicrm_api3_create_success();
  96   } else {
  97     return $result;
  98   }
  99 }
 100
 101 /**
 102  * Enable an extension
 103  *
 104  * @param  array       $params input parameters
 105  *                          - key: string, eg "com.example.myextension"
 106  *                          - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
 107  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 108  *
 109  * @return array API result
 110  * @static void
 111  * @access public
 112  * @example ExtensionEnable.php
 113  *
 114  */
 115 function civicrm_api3_extension_enable($params) {
 116   $keys = _civicrm_api3_getKeys($params);
 117   if (count($keys) == 0) {
 118     return civicrm_api3_create_success();
 119   }
 120
 121   CRM_Extension_System::singleton()->getManager()->enable($keys);
 122   return civicrm_api3_create_success();
 123 }
 124
 125 /**
 126  * Disable an extension
 127  *
 128  * @param  array       $params input parameters
 129  *                          - key: string, eg "com.example.myextension"
 130  *                          - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
 131  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 132  *
 133  * @return array API result
 134  * @static void
 135  * @access public
 136  * @example ExtensionDisable.php
 137  *
 138  */
 139 function civicrm_api3_extension_disable($params) {
 140   $keys = _civicrm_api3_getKeys($params);
 141   if (count($keys) == 0) {
 142     return civicrm_api3_create_success();
 143   }
 144
 145   CRM_Extension_System::singleton()->getManager()->disable($keys);
 146   return civicrm_api3_create_success();
 147 }
 148
 149 /**
 150  * Uninstall an extension
 151  *
 152  * @param  array       $params input parameters
 153  *                          - key: string, eg "com.example.myextension"
 154  *                          - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
 155  *                            using 'keys' should be more performant than making multiple API calls with 'key'
 156  *                          - removeFiles: bool, whether to remove source tree; default: FALSE
 157  *
 158  * @return array API result
 159  * @static void
 160  * @access public
 161  * @example ExtensionUninstall.php
 162  *
 163  */
 164 function civicrm_api3_extension_uninstall($params) {
 165   $keys = _civicrm_api3_getKeys($params);
 166   if (count($keys) == 0) {
 167     return civicrm_api3_create_success();
 168   }
 169
 170   // TODO // $removeFiles = CRM_Utils_Array::value('removeFiles', $params, FALSE);
 171   CRM_Extension_System::singleton()->getManager()->uninstall($keys);
 172   return civicrm_api3_create_success();
 173 }
 174
 175 /**
 176  * Download and install an extension
 177  *
 178  * @param  array $params input parameters
 179  *                          - key: string, eg "com.example.myextension"
 180  *                          - url: string eg "http://repo.com/myextension-1.0.zip"
 181  *
 182  * @throws API_Exception
 183  * @return array API result
 184  * @static void
 185  * @access public
 186  * @example ExtensionDownload.php
 187  */
 188 function civicrm_api3_extension_download($params) {
 189   if (! array_key_exists('key', $params)) {
 190     throw new API_Exception('Missing required parameter: key');
 191   }
 192
 193   if (! array_key_exists('url', $params)) {
 194     if (! CRM_Extension_System::singleton()->getBrowser()->isEnabled()) {
 195       throw new API_Exception('Automatic downloading is diabled. Try adding parameter "url"');
 196     }
 197     if ($reqs = CRM_Extension_System::singleton()->getBrowser()->checkRequirements()) {
 198       $first = array_shift($reqs);
 199       throw new API_Exception($first['message']);
 200     }
 201     if ($info = CRM_Extension_System::singleton()->getBrowser()->getExtension($params['key'])) {
 202       if ($info->downloadUrl) {
 203         $params['url'] = $info->downloadUrl;
 204       }
 205     }
 206   }
 207
 208   if (! array_key_exists('url', $params)) {
 209     throw new API_Exception('Cannot resolve download url for extension. Try adding parameter "url"');
 210   }
 211
 212   foreach (CRM_Extension_System::singleton()->getDownloader()->checkRequirements() as $requirement) {
 213     return civicrm_api3_create_error($requirement['message']);
 214   }
 215
 216   if (! CRM_Extension_System::singleton()->getDownloader()->download($params['key'], $params['url'])) {
 217     return civicrm_api3_create_error('Download failed - ZIP file is unavailable or malformed');
 218   }
 219   CRM_Extension_System::singleton()->getCache()->flush();
 220   CRM_Extension_System::singleton(TRUE);
 221   CRM_Extension_System::singleton()->getManager()->install(array($params['key']));
 222
 223   return civicrm_api3_create_success();
 224 }
 225
 226 /**
 227  * Download and install an extension
 228  *
 229  * @param  array       $params input parameters
 230  *                          - local: bool, whether to rescan local filesystem (default: TRUE)
 231  *                          - remote: bool, whether to rescan remote repository (default: TRUE)
 232  *
 233  * @return array API result
 234  * @static void
 235  * @access public
 236  * @example ExtensionRefresh.php
 237  *
 238  */
 239 function civicrm_api3_extension_refresh($params) {
 240   $defaults = array('local' => TRUE, 'remote' => TRUE);
 241   $params = array_merge($defaults, $params);
 242
 243   $system = CRM_Extension_System::singleton(TRUE);
 244
 245   if ($params['local']) {
 246     $system->getManager()->refresh();
 247     $system->getManager()->getStatuses(); // force immediate scan
 248   }
 249
 250   if ($params['remote']) {
 251     if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements)) {
 252       $system->getBrowser()->refresh();
 253       $system->getBrowser()->getExtensions(); // force immediate download
 254     }
 255   }
 256
 257   return civicrm_api3_create_success();
 258 }
 259
 260 /**
 261  * Get a list of available extensions
 262  *
 263  * @param $params
 264  *
 265  * @return array API result
 266  * @static void
 267  * @access public
 268  * @example ExtensionGet.php
 269  */
 270 function civicrm_api3_extension_get($params) {
 271   $statuses = CRM_Extension_System::singleton()->getManager()->getStatuses();
 272   $mapper = CRM_Extension_System::singleton()->getMapper();
 273   $result = array();
 274   foreach ($statuses as $key => $status) {
 275     //try {
 276     //  $info = (array) $mapper->keyToInfo($key);
 277     //} catch (CRM_Extension_Exception $e) {
 278       $info = array();
 279       $info['key'] = $key;
 280     //}
 281     $info['status'] = $status;
 282     $result[] = $info;
 283   }
 284   return civicrm_api3_create_success($result);
 285 }
 286
 287 /**
 288  * Determine the list of extension keys
 289  *
 290  * @param array $params API request params with 'key' or 'keys'
 291  * @return array of extension keys
 292  * @throws API_Exception
 293  */
 294 function _civicrm_api3_getKeys($params) {
 295   if (array_key_exists('keys', $params) && is_array($params['keys'])) {
 296     return $params['keys'];
 297   } elseif (array_key_exists('keys', $params) && is_string($params['keys'])) {
 298     if ($params['keys'] == '') {
 299       return array();
 300     } else {
 301       return explode(API_V3_EXTENSION_DELIMITER, $params['keys']);
 302     }
 303   } elseif (array_key_exists('key', $params)) {
 304     return array($params['key']);
 305   } else {
 306     throw new API_Exception('Missing required parameter: key or keys');
 307   }
 308 }