Exceptions to json output

README.md

@@ -44,6 +44,9 @@ Which will result in:
 }
 ```
 
+For a collection response, data is an array of resources.
+Errors can also be send as response, even automatically by exceptions.
+
 Examples for all kind of responses are in the [/examples](/examples) directory.
 
 

examples/errors_exception_direct.php

@@ -0,0 +1,28 @@
+<?php
+
+use alsvanzelf\jsonapi;
+
+ini_set('display_errors', 1);
+error_reporting(-1);
+
+require '../vendor/autoload.php';
+
+/**
+ * via an exception
+ * 
+ * @note previous exceptions will be added as well
+ * @note exceptions only output file, line, trace if the display_errors directive is true
+ *       you can tune it with that, or by setting jsonapi\base::$debug to false
+ * @note echo'ing the exception has the same effect as using ->send_response()
+ */
+
+try {
+	$http_status = jsonapi\response::STATUS_NOT_FOUND;
+	$friendly_message = 'We don\'t know this user.';
+	$about_link = 'www.example.com/search';
+	throw new jsonapi\exception('unknown user', $http_status, $previous=null, $friendly_message, $about_link);
+}
+catch (Exception $e) {
+	echo $e;
+	exit;
+}

examples/index.html

@@ -28,7 +28,8 @@ <h3>Resources collections</h3>
 
 	<h3>Errors</h3>
 	<ul>
-		<li><a href="errors_exception.php">Via an exception</a></li>
+		<li><a href="errors_exception_direct.php">Via jsonapi's custom exception</a></li>
+		<li><a href="errors_exception_native.php">Via php's native exception</a></li>
 		<li><a href="errors_all_options.php">All options</a></li>
 	</ul>
 

src/errors.php

@@ -17,15 +17,9 @@
  * - meta data @see ->add_meta() or ->fill_meta()
  * - self link @see ->set_self_link()
  * 
- * @note ease error handling by adding this in your own exception handling
- * 
- * ```
- * public function __toString() {
- *     $jsonapi = new \alsvanzelf\jsonapi\errors($this);
- *     $jsonapi->send_response();
- *     return '';
- * }
- * ```
+ * @note ease error handling by using a jsonapi\exception
+ *       @see examples/errors_exception_direct.php
+ *       @see jsonapi\exception::__toString() when you want to use your own exception handling
  */
 
 class errors extends response {
@@ -193,7 +187,7 @@ public function fill_errors($errors) {
  * @param string $friendly_message optional, @see jsonapi\error->set_friendly_message()
  * @param string $about_link       optional, @see jsonapi\error->set_about_link()
  */
-public function add_exception($exception=null, $friendly_message=null, $about_link=null) {
+public function add_exception($exception, $friendly_message=null, $about_link=null) {
 	$error_message = $exception->getMessage();
 	$error_status  = $exception->getCode();
 

src/exception.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace alsvanzelf\jsonapi;
+
+/**
+ * custom exception for use in jsonapi projects
+ * echo'ing the exception (or using ->send_response()) output a errors collection response
+ * 
+ * @note throwing the exception alone doesn't give you json output
+ */
+
+class exception extends \Exception {
+
+/**
+ * internal data containers
+ */
+protected $friendly_message;
+protected $about_link;
+
+/**
+ * custom exception for usage by jsonapi projects
+ * when echo'd, sends a jsonapi\errors response with the exception in it
+ * 
+ * can be thrown as a normal exception, optionally with two extra parameters
+ * 
+ * @param string    $message
+ * @param integer   $code             optional, defaults to 500
+ *                                    if using one of the predefined ones in jsonapi\response::STATUS_*
+ *                                    sends out those as http status
+ * @param Exception $previous
+ * @param string    $friendly_message optional, which message to output to clients
+ *                                    the exception $message is hidden unless base::$debug is true
+ * @param string    $about_link       optional, a url to send clients to for more explanation
+ *                                    i.e. a link to the api documentation
+ */
+public function __construct($message='', $code=0, $previous=null, $friendly_message=null, $about_link=null) {
+	parent::__construct($message, $code, $previous);
+
+	if ($friendly_message) {
+		$this->set_friendly_message($friendly_message);
+	}
+	if ($about_link) {
+		$this->set_about_link($about_link);
+	}
+}
+
+/**
+ * sets a main user facing message
+ * 
+ * @see error->set_friendly_message()
+ */
+public function set_friendly_message($friendly_message) {
+	$this->friendly_message = $friendly_message;
+}
+
+/**
+ * sets a link which can help in solving the problem
+ * 
+ * @see error->set_about_link()
+ */
+public function set_about_link($about_link) {
+	$this->about_link = $about_link;
+}
+
+/**
+ * sends out the json response of an jsonapi\errors object to the browser
+ * 
+ * @see errors->send_response()
+ */
+public function send_response($content_type=null, $encode_options=null, $response=null) {
+	$jsonapi = new errors($this, $this->friendly_message, $this->about_link);
+	$jsonapi->send_response($content_type, $encode_options, $response);
+	exit;
+}
+
+/**
+ * alias for ->send_response()
+ * 
+ * @return string empty for sake of correctness
+ *                as ->send_response() already echo's the json and terminates script execution
+ */
+public function __toString() {
+	$this->send_response();
+	return '';
+}
+
+}