api/v3/Extension.php

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