api/Exception.php

   1 <?php
   2 /**
   3  * File for the CiviCRM APIv3 API wrapper
   4  *
   5  * @package CiviCRM_APIv3
   6  * @subpackage API
   7  *
   8  * @copyright CiviCRM LLC (c) 2004-2014
   9  */
  10
  11 /**
  12  * This api exception returns more information than the default one. The aim it let the api consumer know better what is exactly the error without having to parse the error message.
  13  * If you consume an api that doesn't return an error_code or the extra data you need, consider improving the api and contribute
  14  */
  15 class API_Exception extends Exception {
  16   const UNAUTHORIZED = 'unauthorized';
  17   const NOT_IMPLEMENTED = 'not-found';
  18
  19   private $extraParams = array();
  20
  21   /**
  22    * @param string $message
  23    *   The human friendly error message.
  24    * @param mixed $error_code
  25    *   A computer friendly error code. By convention, no space (but underscore
  26    *   allowed) (ex: mandatory_missing, duplicate, invalid_format).
  27    * @param array $extraParams
  28    *   Extra params to return. eg an extra array of ids. It is not mandatory,
  29    *   but can help the computer using the api. Keep in mind the api consumer
  30    *   isn't to be trusted. eg. the database password is NOT a good extra data.
  31    * @param Exception|NULL $previous
  32    *   A previous exception which caused this new exception.
  33    */
  34   public function __construct($message, $error_code = 0, $extraParams = array(), Exception $previous = NULL) {
  35     // Using int for error code "old way") ?
  36     if (is_numeric($error_code)) {
  37       $code = $error_code;
  38     }
  39     else {
  40       $code = 0;
  41     }
  42     parent::__construct(ts($message), $code, $previous);
  43     $this->extraParams = $extraParams + array('error_code' => $error_code);
  44   }
  45
  46   // custom string representation of object
  47   /**
  48    * @return string
  49    */
  50   public function __toString() {
  51     return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
  52   }
  53
  54   /**
  55    * @return array
  56    */
  57   public function getExtraParams() {
  58     return $this->extraParams;
  59   }
  60
  61   /**
  62    * @return array
  63    */
  64   public function getErrorCodes() {
  65     return array(
  66       2000 => '$params was not an array',
  67       2001 => 'Invalid Value for Date field',
  68       2100 => 'String value is longer than permitted length',
  69       self::UNAUTHORIZED => 'Unauthorized',
  70       self::NOT_IMPLEMENTED => 'Entity or method is not implemented',
  71     );
  72   }
  73 }
  74
  75 /**
  76  * This api exception returns more information than the default one. We are using it rather than
  77  * API_Exception from the api wrapper as the namespace is more generic
  78  */
  79 class CiviCRM_API3_Exception extends Exception {
  80   private $extraParams = array();
  81
  82   /**
  83    * @param string $message
  84    *   The human friendly error message.
  85    * @param mixed $error_code
  86    *   A computer friendly error code. By convention, no space (but underscore
  87    *   allowed) (ex: mandatory_missing, duplicate, invalid_format).
  88    * @param array $extraParams
  89    *   Extra params to return. eg an extra array of ids. It is not mandatory,
  90    *   but can help the computer using the api. Keep in mind the api consumer
  91    *   isn't to be trusted. eg. the database password is NOT a good extra data.
  92    * @param Exception|NULL $previous
  93    *   A previous exception which caused this new exception.
  94    */
  95   public function __construct($message, $error_code, $extraParams = array(), Exception $previous = NULL) {
  96     parent::__construct(ts($message));
  97     $this->extraParams = $extraParams + array('error_code' => $error_code);
  98   }
  99
 100   // custom string representation of object
 101   /**
 102    * @return string
 103    */
 104   public function __toString() {
 105     return __CLASS__ . ": [{$this->extraParams['error_code']}: {$this->message}\n";
 106   }
 107
 108   /**
 109    * @return mixed
 110    */
 111   public function getErrorCode() {
 112     return $this->extraParams['error_code'];
 113   }
 114
 115   /**
 116    * @return array
 117    */
 118   public function getExtraParams() {
 119     return $this->extraParams;
 120   }
 121 }