platform/classes/Q/Exception.php - Q Platform
Show:

File: platform/classes/Q/Exception.php

  1. <?php
  2.  
  3. /**
  4.  * @module Q
  5.  */
  6. class Q_Exception extends Exception
  7. {	
  8. 	/**
  9. 	 * Represents a complex exception thrown in Q. It may contain more details.
  10. 	 * @class Q_Exception
  11.  	 * @constructor
  12. 	 * @extends Exception
  13. 	 * @param {array} [$params=array()] Array of parameters for the exception. 
  14. 	 *  Used in the exception message, etc.
  15. 	 *  To access them later, call $e->params()
  16. 	 *  You can also provide a string here, which will
  17. 	 *  then be the exception message.
  18. 	 * @param {array} [$inputFields=array()] Array of names of input fields to which the exception applies.
  19. 	 * @param {array} [$code=null] Optionally pass the error code here to override the default
  20. 	 */
  21. 	function __construct(
  22. 	  $params = array(),
  23. 	  $inputFields = array(),
  24. 	  $code = null,
  25. 	  $file = null,
  26. 	  $line = null,
  27. 	  $trace = null,
  28. 	  $traceAsString = null)
  29. 	{
  30. 		if (is_string($inputFields)) {
  31. 			$inputFields = array($inputFields);
  32. 		}
  33. 		$this->inputFields = $inputFields;
  34. 		if (isset($file)) {
  35. 			$this->file = $file;
  36. 		}
  37. 		if (isset($line)) {
  38. 			$this->line = $line;
  39. 		}
  40. 		if (isset($trace)) {
  41. 			$this->trace = $trace;
  42. 		}
  43. 		if (isset($traceAsString)) {
  44. 			$this->traceAsString = $traceAsString;
  45. 		}
  46. 		
  47. 		if (is_string($params)) {
  48. 			parent::__construct($params, is_numeric($code) ? $code : -1);
  49. 			if (isset($code)) {
  50. 				$this->code = $code; // Q_Exception allows non-numeric codes
  51. 			}
  52. 			return;
  53. 		}
  54. 		$this->params = is_array($params) ? $params : array();
  55.  
  56. 		$className = get_class($this);
  57. 		$message = isset(self::$messages[$className])
  58. 			? Q::interpolate(self::$messages[$className], $this->params)
  59. 			: $className;
  60. 		$code = isset($code) ? $code : 
  61. 			(isset(self::$codes[$className]) ? self::$codes[$className] : 1);
  62. 		parent::__construct($message, $code);
  63. 	}
  64. 	
  65. 	/**
  66. 	 * Construct a Q_Exception object from an Exception.
  67. 	 * @method $exception
  68. 	 * @param $exception
  69. 	 * @return {Q_Exception}
  70. 	 */
  71. 	static function fromException($exception)
  72. 	{
  73. 		$result = new Q_Exception();
  74. 		$fields = get_object_vars($exception);
  75. 		foreach ($fields as $k => $v) {
  76. 			$result->$k = $v;
  77. 		}
  78. 		return $result;
  79. 	}
  80. 	
  81. 	/**
  82. 	 * @method __get
  83. 	 * @param {string} $param
  84. 	 * @return {mixed}
  85. 	 */
  86. 	function __get($param)
  87. 	{
  88. 		return isset($this->params[$param])
  89. 			? $this->params[$param]
  90. 			: null;
  91. 	}
  92. 	
  93. 	/**
  94. 	 * @method __set
  95. 	 * @param {string} $param
  96. 	 * @param {mixed} $value
  97. 	 */
  98. 	function __set($param, $value) {
  99. 		$this->params[$param] = $value;
  100. 	}
  101. 	
  102. 	/**
  103. 	 * Returns the array of parameters the exception was created with.
  104. 	 * @method params
  105. 	 * @return {array}
  106. 	 */
  107. 	function params()
  108. 	{
  109. 		return $this->params;
  110. 	}
  111. 	
  112. 	/**
  113. 	 * Returns the array of names of input fields the exception applies to.
  114. 	 * @method inputFields
  115. 	 * @return {array}
  116. 	 */
  117. 	function inputFields()
  118. 	{
  119. 		return $this->inputFields;
  120. 	}
  121. 	
  122. 	/**
  123. 	 * Registers a new exception class that extends Q_Exception
  124. 	 * @method add
  125. 	 * @static
  126. 	 * @param {string} $className The name of the exception class.
  127. 	 * @param {string} $message The description of the error. Will be eval()-ed before rendering,
  128. 	 *  so it can include references to parameters, such as $my_param.
  129. 	 * @param {array} [$rethrowDestClasses=array()] The name of the class that should handle this exception,
  130. 	 * @param {string} [$baseClassName=null] Here you can pass the name of different base class than Q_Exception
  131. 	 *  should it be thrown. Almost all catch() blocks in your code should use
  132. 	 *  `Q_Exception::rethrow($e, __CLASS__)` as the first statement, 
  133. 	 *  if the exception might have to be re-thrown further down the stack.
  134. 	 */
  135. 	static function add(
  136. 	 $className,
  137. 	 $message,
  138. 	 $rethrowDestClasses = array(),
  139. 	 $baseClassName = null)
  140. 	{
  141. 		if (is_string($rethrowDestClasses)) {
  142. 			$baseClassName = $rethrowDestClasses;
  143. 			$rethrowDestClasses = array();
  144. 		}
  145. 		static $exception_code = 10000;
  146. 		++$exception_code; // TODO: improve this somehow
  147. 		self::$codes[$className] = $exception_code;
  148. 		self::$messages[$className] = $message;
  149. 		self::$rethrowDestClasses[$className] = $rethrowDestClasses;
  150. 		if (is_array($baseClassName)) {
  151. 			$rethrowDestClasses = $baseClassName;
  152. 			$baseClassName = null;
  153. 		}
  154. 		if (isset($baseClassName)) {
  155. 			self::$baseClasses[$className] = isset($baseClass) ? $baseClass : 'Q_Exception';
  156. 		}
  157. 	}
  158. 	
  159. 	/**
  160. 	 * Use in your catch() blocks if you think the exception 
  161. 	 * might have to be thrown further down the stack.
  162. 	 * @method rethrow
  163. 	 * @static
  164. 	 * @param {Exception} $exception The exception that was thrown. It is analyzed for
  165. 	 *  whether it should be re-thrown.
  166. 	 * @param {string} $currentClass If the $rethrowDestClasses was specified in Q_Exception::add
  167. 	 *  when creating this exception's class, and it does not contain
  168. 	 *  $currentClass, this function throws the exception again.
  169. 	 */
  170. 	static function rethrow(
  171. 	 $exception, 
  172. 	 $currentClass)
  173. 	{
  174. 		if (!is_callable(array($exception, 'rethrowDestClasses'))) {
  175. 			return false;
  176. 		}
  177.  
  178. 		$rdc = $exception->rethrowDestClasses();
  179. 		if ($rdc and !in_array($currentClass, $rdc)) {
  180. 			throw $exception;
  181. 		}
  182. 	}
  183. 	
  184. 	/**
  185. 	 * Returns an array of classes to rethrow to, if any.
  186. 	 * @method rethrowDestClasses
  187. 	 * @return {array}
  188. 	 */
  189. 	function rethrowDestClasses()
  190. 	{
  191. 		$className = get_class($this);
  192. 		if (isset(self::$rethrowDestClasses[$className])) {
  193. 			return self::$rethrowDestClasses[$className];
  194. 		}
  195. 		return array();
  196. 	}
  197. 	
  198. 	/**
  199. 	 * Returns the trace array, can be overridden. Use this in your exception reporting.
  200. 	 * This is the default implementation.
  201. 	 * @method getTraceEx
  202. 	 * @return {array}
  203. 	 */
  204. 	function getTraceEx()
  205. 	{
  206. 		if (isset($this->trace)) {
  207. 			return $this->trace;
  208. 		}
  209. 		return parent::getTrace();
  210. 	}
  211. 	
  212. 	/**
  213. 	 * Returns trace as string, can be overridden. Use this in your exception reporting.
  214. 	 * This is the default implementation.
  215. 	 * @method getTraceAsStringEx
  216. 	 * @return {string}
  217. 	 */
  218. 	function getTraceAsStringEx()
  219. 	{
  220. 		if (isset($this->traceAsString)) {
  221. 			return $this->traceAsString;
  222. 		}
  223. 		return parent::getTraceAsString();
  224. 	}
  225. 	
  226. 	/**
  227. 	 * Converts an exception or array of exceptions to an array
  228. 	 * @method toArray
  229. 	 * @static
  230. 	 * @param {Exception|array} $exceptions The exception object or array of exceptions to convert
  231. 	 * @return {array}
  232. 	 */
  233. 	static function toArray($exceptions)
  234. 	{
  235. 		if (empty($exceptions)) {
  236. 			return array();
  237. 		}
  238. 		$array_was_passed = true;
  239. 		if (!is_array($exceptions)) {
  240. 			$exceptions = array($exceptions);
  241. 			$array_was_passed = false;
  242. 		}
  243. 		$results = array();
  244. 		$show_fal = Q_Config::get('Q', 'exception', 'showFileAndLine', true);
  245. 		$show_trace = Q_Config::get('Q', 'exception', 'showTrace', true);
  246. 		foreach ($exceptions as $e) {
  247. 			if (!($e instanceof Exception)) {
  248. 				continue;
  249. 			}
  250. 			$message = $e->getMessage();
  251. 			$code = $e->getCode();
  252. 			if ($show_fal) {
  253. 				$line = $e->getLine();
  254. 				$file = $e->getFile();
  255. 			}
  256. 			if ($show_trace) {
  257. 				if (is_callable(array($e, 'getTraceEx'))) {
  258. 					$trace = $e->getTraceEx();
  259. 				} else {
  260. 					$trace = $e->getTrace();
  261. 				}
  262. 			}
  263. 			$fields = null;
  264. 			if (is_callable(array($e, 'inputFields'))) {
  265. 				$fields = $e->inputFields();
  266. 			}
  267. 			$classname = get_class($e);
  268. 			$results[] = compact('message', 'code', 'line', 'file', 'trace', 'fields', 'classname');
  269. 		}
  270. 		if ($array_was_passed) {
  271. 			return $results;
  272. 		} else {
  273. 			$ret = reset($results);
  274. 			return $ret ? $ret : array();
  275. 		}
  276. 	}
  277. 	
  278. 	/**
  279. 	 * Return colored text that you can output in logs or text mode
  280. 	 * @return {string}
  281. 	 */
  282. 	function colored()
  283. 	{
  284. 		return self::coloredString($this);
  285. 	}
  286. 	
  287. 	/**
  288. 	 * Return colored text that you can output in logs or text mode
  289. 	 * Pass an exception or 
  290. 	 * @param {string|Exception} $exception The exception or an exception message. If the later, you must pass three more arguments.
  291. 	 * @param {string} [$file]
  292. 	 * @param {string} [$line]
  293. 	 * @param {string} [$trace]
  294. 	 * @return {string}
  295. 	 */
  296. 	static function coloredString($message, $file=null, $line=null, $trace=null)
  297. 	{
  298. 		if ($message instanceof Exception) {
  299. 			$e = $message;
  300. 			$traceString = is_callable(array($e, 'getTraceAsStringEx'))
  301. 				? $e->getTraceAsStringEx()
  302. 				: $e->getTraceAsString();
  303. 			return self::coloredString(
  304. 				$e->getMessage(),
  305. 				$e->getFile(),
  306. 				$e->getLine(),
  307. 				$traceString
  308. 			);
  309. 		}
  310. 		$colors = Q_Config::get('Q', 'exception', 'colors', array());
  311. 		Q::autoload('Q_Utils');
  312. 		$fields = array(
  313. 			'message' => $message,
  314. 			'fileAndLine' => "in $file ($line)",
  315. 			'trace' => $trace
  316. 		);
  317. 		foreach ($fields as $f => $v) {
  318. 			$c0 = isset($colors[$f][0]) ? $colors[$f][0] : null;
  319. 			$c1 = isset($colors[$f][1]) ? $colors[$f][1] : null;
  320. 			$fields[$f] = Q_Utils::colored($v, $c0, $c1);
  321. 		}
  322. 		$reset = Q_Utils::colored("", "", "");
  323. 		return "$fields[message]\n\n$fields[fileAndLine]\n$fields[trace]\n";
  324. 	}
  325. 	
  326. 	/**
  327. 	 * @property $params
  328. 	 * @protected
  329. 	 * @type array
  330. 	 */
  331. 	public $params = array();
  332. 	/**
  333. 	 * @property $inputFields
  334. 	 * @protected
  335. 	 * @type array
  336. 	 */
  337. 	public $inputFields = array();
  338. 	
  339. 	/**
  340. 	 * @property $codes
  341. 	 * @protected
  342. 	 * @type array
  343. 	 */
  344. 	protected static $codes = array();
  345. 	/**
  346. 	 * @property $messages
  347. 	 * @protected
  348. 	 * @type array
  349. 	 */
  350. 	protected static $messages = array();
  351. 	/**
  352. 	 * @property $rethrowDestClasses
  353. 	 * @protected
  354. 	 * @type array
  355. 	 */
  356. 	protected static $rethrowDestClasses = array();
  357. 	/**
  358. 	 * @property $baseClasses
  359. 	 * @protected
  360. 	 * @type array
  361. 	 */
  362. 	protected static $baseClasses = array();
  363. 	/**
  364. 	 * @property $trace
  365. 	 * @protected
  366. 	 * @type array
  367. 	 */
  368. 	protected $trace = null;
  369. 	/**
  370. 	 * @property $traceAsString
  371. 	 * @protected
  372. 	 * @type string
  373. 	 */
  374. 	protected $traceAsString = null;
  375. 	/**
  376. 	 * @property $code
  377. 	 * @protected
  378. 	 * @type string
  379. 	 */
  380. 	protected $code = null;
  381. }
  382.  
  383.