From 6b359437509fdc0339c0f921f75a63c73d39a91a Mon Sep 17 00:00:00 2001
From: eileen <eileen@fuzion.co.nz>
Date: Fri, 5 Jul 2013 19:29:30 +1200
Subject: [PATCH] CRM-13016 add civicrm_api3 wrapper

---
 api/Exception.php                | 28 ++++++++++++++++++++++++++++
 api/api.php                      | 16 ++++++++++++++++
 tests/phpunit/api/v3/APITest.php | 30 ++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+)

diff --git a/api/Exception.php b/api/Exception.php
index e8f24e4e01..ea4705820e 100644
--- a/api/Exception.php
+++ b/api/Exception.php
@@ -48,3 +48,31 @@ class API_Exception extends Exception
         );
   }
 }
+/**
+ * This api exception returns more information than the default one. We are using it rather than
+ * API_Exception from the api wrapper as the namespace is more generic
+ * @param string $message the human friendly error message
+ * @param string $error_code a computer friendly error code. By convention, no space (but underscore allowed)
+ *  ex: mandatory_missing, duplicate, invalid_format
+ * @param array $data extra params to return. eg an extra array of ids. It is not mandatory, but can help the computer using the api. Keep in mind the api consumer isn't to be trusted. eg. the database password is NOT a good extra data
+ */
+class CiviCRM_API3_Exception extends Exception
+{
+  private $extraParams = array();
+  public function __construct($message, $error_code, $extraParams = array(),Exception $previous = null) {
+    parent::__construct(ts($message));
+    $this->extraParams = $extraParams + array('error_code' => $error_code);
+  }
+
+  // custom string representation of object
+  public function __toString() {
+    return __CLASS__ . ": [{$this->extraParams['error_code']}: {$this->message}\n";
+  }
+
+  public function getErrorCode() {
+    return $this->extraParams['error_code'];
+  }
+  public function getExtraParams() {
+    return $this->extraParams;
+  }
+}
diff --git a/api/api.php b/api/api.php
index 84f0a99330..3ade1a5b39 100644
--- a/api/api.php
+++ b/api/api.php
@@ -238,6 +238,22 @@ function _civicrm_api_resolve($apiRequest) {
   $cache[$cachekey] = array('function' => FALSE, 'is_generic' => FALSE);
   return $cache[$cachekey];
 }
+/**
+ * Version 3 wrapper for civicrm_api. Throws exception
+ * @param string $entity type of entities to deal with
+ * @param string $action create, get, delete or some special action name.
+ * @param array $params array to be passed to function
+ *
+ * @return array
+ *
+ */
+function civicrm_api3($entity, $action, $params){
+  $params['version'] = 3;
+  $result = civicrm_api($entity, $action, $params);
+  if($result['is_error']){
+    throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array::value('error_code', $result, 'undefined'), $result);
+  }
+}
 
 /**
  * Load/require all files related to an entity.
diff --git a/tests/phpunit/api/v3/APITest.php b/tests/phpunit/api/v3/APITest.php
index 7cb1b6f2a9..5b7f8af042 100644
--- a/tests/phpunit/api/v3/APITest.php
+++ b/tests/phpunit/api/v3/APITest.php
@@ -168,5 +168,35 @@ class api_v3_APITest extends CiviUnitTestCase {
       $this->assertEquals($expected, $actual, sprintf('input=%s expected=%s actual=%s', $input, $expected, $actual));
     }
   }
+/**
+ * Test that calling via wrapper works
+ */
+  function testv3Wrapper() {
+    try{
+      $result = civicrm_api3('contact', 'get', array());
+    }
+    catch (CRM_Exception $e){
+      $this->fail("This should have been a success test");
+    }
+    $this->assertAPISuccess($result);
+  }
+
+  /**
+   * test exception is thrown
+   */
+  function testv3WrapperException(){
+    try{
+      $result = civicrm_api3('contact', 'create', array('debug' => 1));
+    }
+    catch (CiviCRM_API3_Exception $e){
+      $this->assertEquals('undefined', $e->getErrorCode());
+      $this->assertEquals('Mandatory key(s) missing from params array: contact_type', $e->getMessage());
+      $extra = $e->getExtraParams();
+      $this->assertArrayHasKey('trace', $extra);
+      return;
+    }
+    $this->fail('Exception was expected');
+  }
+
 }
 
-- 
2.25.1