api/v3/Cxn.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   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 /**
  29  * The Cxn API allows a Civi site to initiate a connection to a
  30  * remote application. There are three primary actions:
  31  *
  32  *  - register: Establish a new connection.
  33  *  - unregister: Destroy an existing connection.
  34  *  - get: Get a list of existing connections.
  35  */
  36
  37 /**
  38  * Adjust metadata for "register" action.
  39  *
  40  * @param array $spec
  41  *   List of fields.
  42  */
  43 function _civicrm_api3_cxn_register_spec(&$spec) {
  44   $daoFields = CRM_Cxn_DAO_Cxn::fields();
  45   $spec['app_guid'] = $daoFields['app_guid'];
  46   $spec['app_meta_url'] = [
  47     'name' => 'app_meta_url',
  48     'type' => CRM_Utils_Type::T_STRING,
  49     'title' => ts('Application Metadata URL'),
  50     'description' => 'Application Metadata URL',
  51     'maxlength' => 255,
  52     'size' => CRM_Utils_Type::HUGE,
  53   ];
  54 }
  55
  56 /**
  57  * Register with a remote application and create a new connection.
  58  *
  59  * One should generally identify an application using the app_guid.
  60  * However, if you need to test a new/experimental application, then
  61  * disable CIVICRM_CXN_CA and specify app_meta_url.
  62  *
  63  * @param array $params
  64  *   Array with keys:
  65  *   - app_guid: The unique identifer of the target application.
  66  *   - app_meta_url: The URL for the application's metadata.
  67  * @return array
  68  * @throws Exception
  69  */
  70 function civicrm_api3_cxn_register($params) {
  71   if (!empty($params['app_meta_url'])) {
  72     list ($status, $json) = CRM_Utils_HttpClient::singleton()->get($params['app_meta_url']);
  73     if (CRM_Utils_HttpClient::STATUS_OK != $status) {
  74       throw new API_Exception("Failed to download appMeta. (Bad HTTP response)");
  75     }
  76     $appMeta = json_decode($json, TRUE);
  77     if (empty($appMeta)) {
  78       throw new API_Exception("Failed to download appMeta. (Malformed)");
  79     }
  80   }
  81   elseif (!empty($params['app_guid'])) {
  82     $appMeta = civicrm_api3('CxnApp', 'getsingle', [
  83       'appId' => $params['app_guid'],
  84     ]);
  85   }
  86
  87   if (empty($appMeta) || !is_array($appMeta)) {
  88     throw new API_Exception("Missing expected parameter: app_guid");
  89   }
  90   \Civi\Cxn\Rpc\AppMeta::validate($appMeta);
  91
  92   try {
  93     /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
  94     $client = \Civi::service('cxn_reg_client');
  95     list($cxnId, $result) = $client->register($appMeta);
  96     CRM_Cxn_BAO_Cxn::updateAppMeta($appMeta);
  97   }
  98   catch (Exception $e) {
  99     CRM_Cxn_BAO_Cxn::updateAppMeta($appMeta);
 100     throw $e;
 101   }
 102
 103   return $result;
 104 }
 105
 106 /**
 107  * Adjust metadata for cxn unregister.
 108  *
 109  * @param array $spec
 110  */
 111 function _civicrm_api3_cxn_unregister_spec(&$spec) {
 112   $daoFields = CRM_Cxn_DAO_Cxn::fields();
 113   $spec['cxn_guid'] = $daoFields['cxn_guid'];
 114   $spec['app_guid'] = $daoFields['app_guid'];
 115   $spec['force'] = [
 116     'name' => 'force',
 117     'type' => CRM_Utils_Type::T_BOOLEAN,
 118     'title' => ts('Force'),
 119     'description' => 'Destroy connection even if the remote application is non-responsive.',
 120     'default' => '0',
 121   ];
 122 }
 123
 124 /**
 125  * Unregister with a remote application; destroy an existing connection.
 126  *
 127  * Specify app_guid XOR cxn_guid.
 128  *
 129  * @param array $params
 130  *   Array with keys:
 131  *   - cxn_guid: string
 132  *   - app_guid: string
 133  *   - force: bool
 134  * @return array
 135  */
 136 function civicrm_api3_cxn_unregister($params) {
 137   $cxnId = _civicrm_api3_cxn_parseCxnId($params);
 138   $appMeta = CRM_Cxn_BAO_Cxn::getAppMeta($cxnId);
 139
 140   /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
 141   $client = \Civi::service('cxn_reg_client');
 142   list($cxnId, $result) = $client->unregister($appMeta, CRM_Utils_Array::value('force', $params, FALSE));
 143
 144   return $result;
 145 }
 146
 147 /**
 148  * @param array $params
 149  *   An array with cxn_guid and/or app_guid.
 150  * @return string
 151  *   The CxnId. (If not available, then an exception is thrown.)
 152  *
 153  * @throws API_Exception
 154  */
 155 function _civicrm_api3_cxn_parseCxnId($params) {
 156   $cxnId = NULL;
 157
 158   if (!empty($params['cxn_guid'])) {
 159     $cxnId = $params['cxn_guid'];
 160   }
 161   elseif (!empty($params['app_guid'])) {
 162     $cxnId = CRM_Core_DAO::singleValueQuery('SELECT cxn_guid FROM civicrm_cxn WHERE app_guid = %1', [
 163       1 => [$params['app_guid'], 'String'],
 164     ]);
 165     if (!$cxnId) {
 166       throw new API_Exception("The app_guid does not correspond to an active connection.");
 167     }
 168   }
 169   if (!$cxnId) {
 170     throw new API_Exception('Missing required parameter: cxn_guid');
 171   }
 172   return $cxnId;
 173 }
 174
 175 /**
 176  * Adjust metadata for cxn get action.
 177  *
 178  * @param array $spec
 179  */
 180 function _civicrm_api3_cxn_get_spec(&$spec) {
 181   // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 182   unset($spec['secret']);
 183 }
 184
 185 /**
 186  * Returns an array of Cxn records.
 187  *
 188  * @param array $params
 189  *   Array of one or more valid property_name=>value pairs.
 190  *
 191  * @return array
 192  *   API result array.
 193  */
 194 function civicrm_api3_cxn_get($params) {
 195   // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 196   unset($params['secret']);
 197
 198   $result = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 199   if (is_array($result['values'])) {
 200     foreach (array_keys($result['values']) as $i) {
 201       if (!empty($result['values'][$i]['app_meta'])) {
 202         $result['values'][$i]['app_meta'] = json_decode($result['values'][$i]['app_meta'], TRUE);
 203       }
 204       if (!empty($result['values'][$i]['perm'])) {
 205         $result['values'][$i]['perm'] = json_decode($result['values'][$i]['perm'], TRUE);
 206       }
 207       // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 208       unset($result['values'][$i]['secret']);
 209     }
 210   }
 211
 212   return $result;
 213 }
 214
 215 /**
 216  * Adjust metadata for "getlink" action.
 217  *
 218  * @param array $spec
 219  *   List of fields.
 220  */
 221 function _civicrm_api3_cxn_getlink_spec(&$spec) {
 222   $daoFields = CRM_Cxn_DAO_Cxn::fields();
 223   $spec['app_guid'] = $daoFields['app_guid'];
 224   $spec['cxn_guid'] = $daoFields['cxn_guid'];
 225   $spec['page_name'] = [
 226     'name' => 'page_name',
 227     'type' => CRM_Utils_Type::T_STRING,
 228     'title' => ts('Page Type'),
 229     'description' => 'The type of page (eg "settings")',
 230     'maxlength' => 63,
 231     'size' => CRM_Utils_Type::HUGE,
 232     'api.aliases' => ['page'],
 233   ];
 234 }
 235
 236 /**
 237  *
 238  * @param array $params
 239  *   Array with keys:
 240  *   - cxn_guid OR app_guid: string.
 241  *   - page: string.
 242  * @return array
 243  * @throws Exception
 244  */
 245 function civicrm_api3_cxn_getlink($params) {
 246   $cxnId = _civicrm_api3_cxn_parseCxnId($params);
 247   $appMeta = CRM_Cxn_BAO_Cxn::getAppMeta($cxnId);
 248
 249   if (empty($params['page_name']) || !is_string($params['page_name'])) {
 250     throw new API_Exception("Invalid page");
 251   }
 252
 253   /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
 254   $client = \Civi::service('cxn_reg_client');
 255   return $client->call($appMeta, 'Cxn', 'getlink', [
 256     'page' => $params['page_name'],
 257   ]);
 258 }
 259
 260 /**
 261  *
 262  * @param array $params
 263  * @return array
 264  * @throws Exception
 265  */
 266 function civicrm_api3_cxn_getcfg($params) {
 267   $result = [
 268     'CIVICRM_CXN_CA' => defined('CIVICRM_CXN_CA') ? CIVICRM_CXN_CA : NULL,
 269     'CIVICRM_CXN_VIA' => defined('CIVICRM_CXN_VIA') ? CIVICRM_CXN_VIA : NULL,
 270     'CIVICRM_CXN_APPS_URL' => defined('CIVICRM_CXN_APPS_URL') ? CIVICRM_CXN_APPS_URL : NULL,
 271     'siteCallbackUrl' => CRM_Cxn_BAO_Cxn::getSiteCallbackUrl(),
 272   ];
 273   return civicrm_api3_create_success($result);
 274 }
 275
 276 /**
 277  * Creates or modifies a Cxn row.
 278  *
 279  * @param array $params
 280  *   Array with keys:
 281  *   - id, cxn_guid OR app_guid: string.
 282  *   - is_active: boolean.
 283  *   - options: JSON
 284  * @return page
 285  * @throws Exception
 286  */
 287 function civicrm_api3_cxn_create($params) {
 288   $result = "";
 289
 290   try {
 291     // get the ID
 292     if (!empty($params['id'])) {
 293       $cxnId = $params['id'];
 294     }
 295     else {
 296       $cxnId = _civicrm_api3_cxn_parseCxnId($params);
 297     }
 298
 299     // see if it's sth to update
 300     if (isset($params['options']) || isset($params['is_active'])) {
 301
 302       $dao = new CRM_Cxn_DAO_Cxn();
 303       $dao->id = $cxnId;
 304
 305       if ($dao->find()) {
 306         if (isset($params['is_active'])) {
 307           $dao->is_active = (int) $params['is_active'];
 308         }
 309         if (isset($params['options'])) {
 310           $dao->options = $params['options'];
 311         }
 312
 313         $result = $dao->save();
 314       }
 315
 316     }
 317     return civicrm_api3_create_success($result, $params, 'Cxn', 'create');
 318
 319   }
 320   catch (Exception $ex) {
 321     throw $ex;
 322   }
 323 }