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