api/v3/Cxn.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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'] = array(
  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', array(
  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 function _civicrm_api3_cxn_unregister_spec(&$spec) {
 107   $daoFields = CRM_Cxn_DAO_Cxn::fields();
 108   $spec['cxn_guid'] = $daoFields['cxn_guid'];
 109   $spec['app_guid'] = $daoFields['app_guid'];
 110   $spec['force'] = array(
 111     'name' => 'force',
 112     'type' => CRM_Utils_Type::T_BOOLEAN,
 113     'title' => ts('Force'),
 114     'description' => 'Destroy connection even if the remote application is non-responsive.',
 115     'default' => '0',
 116   );
 117 }
 118
 119 /**
 120  * Unregister with a remote application; destroy an existing connection.
 121  *
 122  * Specify app_guid XOR cxn_guid.
 123  *
 124  * @param array $params
 125  *   Array with keys:
 126  *   - cxn_guid: string
 127  *   - app_guid: string
 128  *   - force: bool
 129  * @return array
 130  */
 131 function civicrm_api3_cxn_unregister($params) {
 132   $cxnId = _civicrm_api3_cxn_parseCxnId($params);
 133   $appMeta = CRM_Cxn_BAO_Cxn::getAppMeta($cxnId);
 134
 135   /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
 136   $client = \Civi::service('cxn_reg_client');
 137   list($cxnId, $result) = $client->unregister($appMeta, CRM_Utils_Array::value('force', $params, FALSE));
 138
 139   return $result;
 140 }
 141
 142 /**
 143  * @param array $params
 144  *   An array with cxn_guid and/or app_guid.
 145  * @return string
 146  *   The CxnId. (If not available, then an exception is thrown.)
 147  *
 148  * @throws API_Exception
 149  */
 150 function _civicrm_api3_cxn_parseCxnId($params) {
 151   $cxnId = NULL;
 152
 153   if (!empty($params['cxn_guid'])) {
 154     $cxnId = $params['cxn_guid'];
 155   }
 156   elseif (!empty($params['app_guid'])) {
 157     $cxnId = CRM_Core_DAO::singleValueQuery('SELECT cxn_guid FROM civicrm_cxn WHERE app_guid = %1', array(
 158       1 => array($params['app_guid'], 'String'),
 159     ));
 160     if (!$cxnId) {
 161       throw new API_Exception("The app_guid does not correspond to an active connection.");
 162     }
 163   }
 164   if (!$cxnId) {
 165     throw new API_Exception('Missing required parameter: cxn_guid');
 166   }
 167   return $cxnId;
 168 }
 169
 170 function _civicrm_api3_cxn_get_spec(&$spec) {
 171   // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 172   unset($spec['secret']);
 173 }
 174
 175 /**
 176  * Returns an array of Cxn records.
 177  *
 178  * @param array $params
 179  *   Array of one or more valid property_name=>value pairs.
 180  *
 181  * @return array
 182  *   API result array.
 183  */
 184 function civicrm_api3_cxn_get($params) {
 185   // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 186   unset($params['secret']);
 187
 188   $result = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 189   if (is_array($result['values'])) {
 190     foreach (array_keys($result['values']) as $i) {
 191       if (!empty($result['values'][$i]['app_meta'])) {
 192         $result['values'][$i]['app_meta'] = json_decode($result['values'][$i]['app_meta'], TRUE);
 193       }
 194       if (!empty($result['values'][$i]['perm'])) {
 195         $result['values'][$i]['perm'] = json_decode($result['values'][$i]['perm'], TRUE);
 196       }
 197       // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
 198       unset($result['values'][$i]['secret']);
 199     }
 200   }
 201
 202   return $result;
 203 }
 204
 205 /**
 206  * Adjust metadata for "getlink" action.
 207  *
 208  * @param array $spec
 209  *   List of fields.
 210  */
 211 function _civicrm_api3_cxn_getlink_spec(&$spec) {
 212   $daoFields = CRM_Cxn_DAO_Cxn::fields();
 213   $spec['app_guid'] = $daoFields['app_guid'];
 214   $spec['cxn_guid'] = $daoFields['cxn_guid'];
 215   $spec['page'] = array(
 216     'name' => 'page',
 217     'type' => CRM_Utils_Type::T_STRING,
 218     'title' => ts('Page Type'),
 219     'description' => 'The type of page (eg "settings")',
 220     'maxlength' => 63,
 221     'size' => CRM_Utils_Type::HUGE,
 222   );
 223 }
 224
 225 /**
 226  *
 227  * @param array $params
 228  *   Array with keys:
 229  *   - cxn_guid OR app_guid: string.
 230  *   - page: string.
 231  * @return array
 232  * @throws Exception
 233  */
 234 function civicrm_api3_cxn_getlink($params) {
 235   $cxnId = _civicrm_api3_cxn_parseCxnId($params);
 236   $appMeta = CRM_Cxn_BAO_Cxn::getAppMeta($cxnId);
 237
 238   if (empty($params['page']) || !is_string($params['page'])) {
 239     throw new API_Exception("Invalid page");
 240   }
 241
 242   /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
 243   $client = \Civi::service('cxn_reg_client');
 244   return $client->call($appMeta, 'Cxn', 'getlink', array(
 245     'page' => $params['page'],
 246   ));
 247 }