4 define('API_V3_EXTENSION_DELIMITER', ',');
7 +--------------------------------------------------------------------+
8 | CiviCRM version 4.3 |
9 +--------------------------------------------------------------------+
10 | Copyright CiviCRM LLC (c) 2004-2013 |
11 +--------------------------------------------------------------------+
12 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
33 * File for the CiviCRM APIv3 extension functions
35 * @package CiviCRM_APIv3
36 * @subpackage API_Extension
38 * @copyright CiviCRM LLC (c) 2004-2013
44 * Install an extension
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'
51 * @return array API result
54 * @example ExtensionInstall.php
57 function civicrm_api3_extension_install($params) {
58 $keys = _civicrm_api3_getKeys($params);
59 if (count($keys) == 0) {
60 return civicrm_api3_create_success();
64 CRM_Extension_System
::singleton()->getManager()->install($keys);
65 } catch (CRM_Extension_Exception
$e) {
66 return civicrm_api3_create_error($e->getMessage());
69 return civicrm_api3_create_success();
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'
80 * @return array API result
83 * @example ExtensionEnable.php
86 function civicrm_api3_extension_enable($params) {
87 $keys = _civicrm_api3_getKeys($params);
88 if (count($keys) == 0) {
89 return civicrm_api3_create_success();
92 CRM_Extension_System
::singleton()->getManager()->enable($keys);
93 return civicrm_api3_create_success();
97 * Disable an extension
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'
104 * @return array API result
107 * @example ExtensionDisable.php
110 function civicrm_api3_extension_disable($params) {
111 $keys = _civicrm_api3_getKeys($params);
112 if (count($keys) == 0) {
113 return civicrm_api3_create_success();
116 CRM_Extension_System
::singleton()->getManager()->disable($keys);
117 return civicrm_api3_create_success();
121 * Uninstall an extension
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
129 * @return array API result
132 * @example ExtensionUninstall.php
135 function civicrm_api3_extension_uninstall($params) {
136 $keys = _civicrm_api3_getKeys($params);
137 if (count($keys) == 0) {
138 return civicrm_api3_create_success();
141 // TODO // $removeFiles = CRM_Utils_Array::value('removeFiles', $params, FALSE);
142 CRM_Extension_System
::singleton()->getManager()->uninstall($keys);
143 return civicrm_api3_create_success();
147 * Download and install an extension
149 * @param array $params input parameters
150 * - key: string, eg "com.example.myextension"
151 * - url: string eg "http://repo.com/myextension-1.0.zip"
153 * @return array API result
156 * @example ExtensionDownload.php
159 function civicrm_api3_extension_download($params) {
160 if (! array_key_exists('key', $params)) {
161 throw new API_Exception('Missing required parameter: key');
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"');
168 if ($reqs = CRM_Extension_System
::singleton()->getBrowser()->checkRequirements()) {
169 $first = array_shift($reqs);
170 throw new API_Exception($first['message']);
172 if ($info = CRM_Extension_System
::singleton()->getBrowser()->getExtension($params['key'])) {
173 if ($info->downloadUrl
) {
174 $params['url'] = $info->downloadUrl
;
179 if (! array_key_exists('url', $params)) {
180 throw new API_Exception('Cannot resolve download url for extension. Try adding parameter "url"');
183 foreach (CRM_Extension_System
::singleton()->getDownloader()->checkRequirements() as $requirement) {
184 return civicrm_api3_create_error($requirement['message']);
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');
190 CRM_Extension_System
::singleton()->getCache()->flush();
191 CRM_Extension_System
::singleton(TRUE);
192 CRM_Extension_System
::singleton()->getManager()->install(array($params['key']));
194 return civicrm_api3_create_success();
198 * Download and install an extension
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)
204 * @return array API result
207 * @example ExtensionRefresh.php
210 function civicrm_api3_extension_refresh($params) {
211 $defaults = array('local' => TRUE, 'remote' => TRUE);
212 $params = array_merge($defaults, $params);
214 $system = CRM_Extension_System
::singleton(TRUE);
216 if ($params['local']) {
217 $system->getManager()->refresh();
218 $system->getManager()->getStatuses(); // force immediate scan
221 if ($params['remote']) {
222 if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements
)) {
223 $system->getBrowser()->refresh();
224 $system->getBrowser()->getExtensions(); // force immediate download
228 return civicrm_api3_create_success();
232 * Get a list of available extensions
234 * @return array API result
237 * @example ExtensionGet.php
240 function civicrm_api3_extension_get($params) {
241 $statuses = CRM_Extension_System
::singleton()->getManager()->getStatuses();
242 $mapper = CRM_Extension_System
::singleton()->getMapper();
244 foreach ($statuses as $key => $status) {
246 // $info = (array) $mapper->keyToInfo($key);
247 //} catch (CRM_Extension_Exception $e) {
251 $info['status'] = $status;
254 return civicrm_api3_create_success($result);
258 * Determine the list of extension keys
260 * @param array $params API request params with 'key' or 'keys'
261 * @return array of extension keys
262 * @throws API_Exception
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'] == '') {
271 return explode(API_V3_EXTENSION_DELIMITER
, $params['keys']);
273 } elseif (array_key_exists('key', $params)) {
274 return array($params['key']);
276 throw new API_Exception('Missing required parameter: key or keys');