3 define('API_V3_EXTENSION_DELIMITER', ',');
6 +--------------------------------------------------------------------+
7 | CiviCRM version 4.3 |
8 +--------------------------------------------------------------------+
9 | Copyright CiviCRM LLC (c) 2004-2013 |
10 +--------------------------------------------------------------------+
11 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
32 * File for the CiviCRM APIv3 extension functions
34 * @package CiviCRM_APIv3
35 * @subpackage API_Extension
37 * @copyright CiviCRM LLC (c) 2004-2013
43 * Install an extension
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'
50 * @return array API result
53 * @example ExtensionInstall.php
56 function civicrm_api3_extension_install($params) {
57 $keys = _civicrm_api3_getKeys($params);
58 if (count($keys) == 0) {
59 return civicrm_api3_create_success();
63 CRM_Extension_System
::singleton()->getManager()->install($keys);
64 } catch (CRM_Extension_Exception
$e) {
65 return civicrm_api3_create_error($e->getMessage());
68 return civicrm_api3_create_success();
74 * @param array $params input parameters
75 * - key: string, eg "com.example.myextension"
76 * - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
77 * using 'keys' should be more performant than making multiple API calls with 'key'
79 * @return array API result
82 * @example ExtensionEnable.php
85 function civicrm_api3_extension_enable($params) {
86 $keys = _civicrm_api3_getKeys($params);
87 if (count($keys) == 0) {
88 return civicrm_api3_create_success();
91 CRM_Extension_System
::singleton()->getManager()->enable($keys);
92 return civicrm_api3_create_success();
96 * Disable an extension
98 * @param array $params input parameters
99 * - key: string, eg "com.example.myextension"
100 * - keys: mixed; array of string, eg array("com.example.myextension1", "com.example.myextension2") or string with comma-delimited list
101 * using 'keys' should be more performant than making multiple API calls with 'key'
103 * @return array API result
106 * @example ExtensionDisable.php
109 function civicrm_api3_extension_disable($params) {
110 $keys = _civicrm_api3_getKeys($params);
111 if (count($keys) == 0) {
112 return civicrm_api3_create_success();
115 CRM_Extension_System
::singleton()->getManager()->disable($keys);
116 return civicrm_api3_create_success();
120 * Uninstall an extension
122 * @param array $params input parameters
123 * - key: string, eg "com.example.myextension"
124 * - keys: array of string, eg array("com.example.myextension1", "com.example.myextension2")
125 * using 'keys' should be more performant than making multiple API calls with 'key'
126 * - removeFiles: bool, whether to remove source tree; default: FALSE
128 * @return array API result
131 * @example ExtensionUninstall.php
134 function civicrm_api3_extension_uninstall($params) {
135 $keys = _civicrm_api3_getKeys($params);
136 if (count($keys) == 0) {
137 return civicrm_api3_create_success();
140 // TODO // $removeFiles = CRM_Utils_Array::value('removeFiles', $params, FALSE);
141 CRM_Extension_System
::singleton()->getManager()->uninstall($keys);
142 return civicrm_api3_create_success();
146 * Download and install an extension
148 * @param array $params input parameters
149 * - key: string, eg "com.example.myextension"
150 * - url: string eg "http://repo.com/myextension-1.0.zip"
152 * @return array API result
155 * @example ExtensionDownload.php
158 function civicrm_api3_extension_download($params) {
159 if (! array_key_exists('key', $params)) {
160 throw new API_Exception('Missing required parameter: key');
163 if (! array_key_exists('url', $params)) {
164 if (! CRM_Extension_System
::singleton()->getBrowser()->isEnabled()) {
165 throw new API_Exception('Automatic downloading is diabled. Try adding parameter "url"');
167 if ($reqs = CRM_Extension_System
::singleton()->getBrowser()->checkRequirements()) {
168 $first = array_shift($reqs);
169 throw new API_Exception($first['message']);
171 if ($info = CRM_Extension_System
::singleton()->getBrowser()->getExtension($params['key'])) {
172 if ($info->downloadUrl
) {
173 $params['url'] = $info->downloadUrl
;
178 if (! array_key_exists('url', $params)) {
179 throw new API_Exception('Cannot resolve download url for extension. Try adding parameter "url"');
182 foreach (CRM_Extension_System
::singleton()->getDownloader()->checkRequirements() as $requirement) {
183 return civicrm_api3_create_error($requirement['message']);
186 if (! CRM_Extension_System
::singleton()->getDownloader()->download($params['key'], $params['url'])) {
187 return civicrm_api3_create_error('Download failed - ZIP file is unavailable or malformed');
189 CRM_Extension_System
::singleton()->getCache()->flush();
190 CRM_Extension_System
::singleton(TRUE);
191 CRM_Extension_System
::singleton()->getManager()->install(array($params['key']));
193 return civicrm_api3_create_success();
197 * Download and install an extension
199 * @param array $params input parameters
200 * - local: bool, whether to rescan local filesystem (default: TRUE)
201 * - remote: bool, whether to rescan remote repository (default: TRUE)
203 * @return array API result
206 * @example ExtensionRefresh.php
209 function civicrm_api3_extension_refresh($params) {
210 $defaults = array('local' => TRUE, 'remote' => TRUE);
211 $params = array_merge($defaults, $params);
213 $system = CRM_Extension_System
::singleton(TRUE);
215 if ($params['local']) {
216 $system->getManager()->refresh();
217 $system->getManager()->getStatuses(); // force immediate scan
220 if ($params['remote']) {
221 if ($system->getBrowser()->isEnabled() && empty($system->getBrowser()->checkRequirements
)) {
222 $system->getBrowser()->refresh();
223 $system->getBrowser()->getExtensions(); // force immediate download
227 return civicrm_api3_create_success();
231 * Get a list of available extensions
233 * @return array API result
236 * @example ExtensionGet.php
239 function civicrm_api3_extension_get($params) {
240 $statuses = CRM_Extension_System
::singleton()->getManager()->getStatuses();
241 $mapper = CRM_Extension_System
::singleton()->getMapper();
243 foreach ($statuses as $key => $status) {
245 // $info = (array) $mapper->keyToInfo($key);
246 //} catch (CRM_Extension_Exception $e) {
250 $info['status'] = $status;
253 return civicrm_api3_create_success($result);
257 * Determine the list of extension keys
259 * @param array $params API request params with 'key' or 'keys'
260 * @return array of extension keys
261 * @throws API_Exception
263 function _civicrm_api3_getKeys($params) {
264 if (array_key_exists('keys', $params) && is_array($params['keys'])) {
265 return $params['keys'];
266 } elseif (array_key_exists('keys', $params) && is_string($params['keys'])) {
267 if ($params['keys'] == '') {
270 return explode(API_V3_EXTENSION_DELIMITER
, $params['keys']);
272 } elseif (array_key_exists('key', $params)) {
273 return array($params['key']);
275 throw new API_Exception('Missing required parameter: key or keys');