CRM/Core/Exception.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * Base class for exceptions generated by CiviCRM.
  14  * This Exception returns more information than the default one. We are using it from the
  15  * form layer to allow redirects to occur without having redirects in the BAO
  16  * @param array $data
  17  *   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.
  18  */
  19 class CRM_Core_Exception extends PEAR_Exception {
  20
  21   const UNAUTHORIZED = 'unauthorized';
  22   const NOT_IMPLEMENTED = 'not-found';
  23
  24   private $errorData = [];
  25
  26   /**
  27    * Class constructor.
  28    *
  29    * @param string $message
  30    *   The human friendly error message.
  31    * @param int|string $error_code
  32    *   A computer friendly error code. By convention, no space (but underscore
  33    *   allowed) (ex: mandatory_missing, duplicate, invalid_format).
  34    * @param array $errorData
  35    *   Extra params to return. eg an extra array of ids. It is not mandatory,
  36    *   but can help the computer using the api. Keep in mind the api consumer
  37    *   isn't to be trusted. eg. the database password is NOT a good extra data.
  38    * @param Throwable|NULL $previous
  39    *   A previous exception which caused this new exception.
  40    */
  41   public function __construct($message, $error_code = 0, $errorData = [], $previous = NULL) {
  42     // Using int for error code "old way") ?
  43     if (is_numeric($error_code)) {
  44       $code = $error_code;
  45     }
  46     else {
  47       $code = 0;
  48     }
  49     // DIVERGENCE: CRM_Core_Exception used `$message`. API_Exception and CiviCRM_API3_Exception used `ts($message)`.
  50     // IMHO, this seems like a terrible place to put `ts()` - civistrings won't detect, and it's hard dependency on l10n services.
  51     parent::__construct($message, $code, $previous);
  52     $this->errorData = $errorData + ['error_code' => $error_code];
  53   }
  54
  55   /**
  56    * Custom string representation of object.
  57    *
  58    * @return string
  59    */
  60   public function __toString() {
  61     return __CLASS__ . ": [{$this->errorData['error_code']}: {$this->message}\n";
  62   }
  63
  64   /**
  65    * Get error code.
  66    *
  67    * @return int|string
  68    */
  69   public function getErrorCode() {
  70     return $this->errorData['error_code'];
  71   }
  72
  73   /**
  74    * Return specific error information.
  75    *
  76    * (Can be used for more detailed error messages or translation.)
  77    *
  78    * This method may be overridden in child exception classes in order
  79    * to add functionality not present in PEAR_Exception and is a placeholder
  80    * to define API
  81    *
  82    * The returned array must be an associative array of parameter => value like so:
  83    * <pre>
  84    * array('name' => $name, 'context' => array(...))
  85    * </pre>
  86    * @return array
  87    */
  88   public function getErrorData() {
  89     return $this->errorData;
  90   }
  91
  92   /**
  93    * Get extra parameters.
  94    *
  95    * @return array
  96    * @deprecated Remove in v6.0. Compatibility with older API_Exception/CiviCRM_API3_Exception contracts.
  97    */
  98   public function getExtraParams() {
  99     return $this->errorData;
 100   }
 101
 102   /**
 103    * Get error codes.
 104    *
 105    * DIVERGENCE: API_Exception defined a discoverable list of error-codes. CRM_Core_Exception and CiviCRM_API3_Exception did not.
 106    *
 107    * @return array
 108    */
 109   public function getErrorCodes() {
 110     return [
 111       2000 => '$params was not an array',
 112       2001 => 'Invalid Value for Date field',
 113       2100 => 'String value is longer than permitted length',
 114       self::UNAUTHORIZED => 'Unauthorized',
 115       self::NOT_IMPLEMENTED => 'Entity or method is not implemented',
 116     ];
 117   }
 118
 119 }