update docblock for setTitle()

[civicrm-core.git] / api / Exception.php

diff --git a/api/Exception.php b/api/Exception.php
index e8f24e4e0157ac9bd745a24ed23eaee64719f10d..953fafdbe99e97481b0ca72d98914c9ddcb276a6 100644 (file)
--- a/api/Exception.php
+++ b/api/Exception.php
@@ -5,7 +5,7 @@
  * @package CiviCRM_APIv3
  * @subpackage API
  *
- * @copyright CiviCRM LLC (c) 2004-2013
+ * @copyright CiviCRM LLC (c) 2004-2014
  */
 
 /**
@@ -21,7 +21,17 @@
  */
 class API_Exception extends Exception
 {
+  const UNAUTHORIZED = 'unauthorized';
+  const NOT_IMPLEMENTED = 'not-found';
+
   private $extraParams = array();
+
+  /**
+   * @param string $message
+   * @param int $error_code
+   * @param array $extraParams
+   * @param Exception $previous
+   */
   public function __construct($message, $error_code = 0, $extraParams = array(),Exception $previous = null) {
     if (is_numeric ($error_code)) // using int for error code "old way")
       $code = $error_code;
@@ -32,19 +42,72 @@ class API_Exception extends Exception
   }
 
   // custom string representation of object
+  /**
+   * @return string
+   */
   public function __toString() {
     return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
   }
 
+  /**
+   * @return array
+   */
   public function getExtraParams() {
     return $this->extraParams;
   }
 
+  /**
+   * @return array
+   */
   public function getErrorCodes(){
     return array(
         2000 => '$params was not an array',
         2001 => 'Invalid Value for Date field',
-        2100 => 'String value is longer than permitted length'
+        2100 => 'String value is longer than permitted length',
+        self::UNAUTHORIZED => 'Unauthorized',
+        self::NOT_IMPLEMENTED => 'Entity or method is not implemented',
         );
   }
 }
+/**
+ * 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();
+
+  /**
+   * @param string $message
+   * @param int $error_code
+   * @param array $extraParams
+   * @param Exception $previous
+   */
+  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
+  /**
+   * @return string
+   */
+  public function __toString() {
+    return __CLASS__ . ": [{$this->extraParams['error_code']}: {$this->message}\n";
+  }
+
+  public function getErrorCode() {
+    return $this->extraParams['error_code'];
+  }
+
+  /**
+   * @return array
+   */
+  public function getExtraParams() {
+    return $this->extraParams;
+  }
+}