From fc65ce8b2be5926b3528f91b5584ca4f51cc9fcf Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Fri, 12 Jun 2015 23:41:09 +0200 Subject: [PATCH 01/11] make the advised custom exception available directly --- examples/errors_exception_direct.php | 29 +++++++++++++++++++ examples/index.html | 1 + src/errors.php | 14 +++++---- src/exception.php | 43 ++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 5 deletions(-) create mode 100644 examples/errors_exception_direct.php create mode 100644 src/exception.php diff --git a/examples/errors_exception_direct.php b/examples/errors_exception_direct.php new file mode 100644 index 0000000..ed839f4 --- /dev/null +++ b/examples/errors_exception_direct.php @@ -0,0 +1,29 @@ +send_response() + */ + +try { + $friendly_message = 'We don\'t know this user.'; + $about_link = 'www.example.com/search'; + throw new \alsvanzelf\jsonapi\exception('unknown user', 404, $previous=null, $friendly_message, $about_link); +} +catch (Exception $e) { + echo $e; + exit; +} diff --git a/examples/index.html b/examples/index.html index 0048572..9d9ea4d 100644 --- a/examples/index.html +++ b/examples/index.html @@ -29,6 +29,7 @@

Resources collections

Errors

diff --git a/src/errors.php b/src/errors.php index a25b4c9..a03b9dd 100644 --- a/src/errors.php +++ b/src/errors.php @@ -17,15 +17,19 @@ * - 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 + * @note ease error handling by using a jsonapi\exception * * ``` - * public function __toString() { - * $jsonapi = new \alsvanzelf\jsonapi\errors($this); - * $jsonapi->send_response(); - * return ''; + * try { + * throw new jsonapi\exception('something went wrong'); + * } + * catch (Exception $e) { + * $e->send_response(); + * exit; * } * ``` + * + * @see jsonapi\exception::__toString() when you want to use your own exception handling */ class errors extends base { diff --git a/src/exception.php b/src/exception.php new file mode 100644 index 0000000..3346a38 --- /dev/null +++ b/src/exception.php @@ -0,0 +1,43 @@ +send_response()) output a errors collection response + * + * @note throwing the exception alone doesn't give you json output + */ + +class exception extends \Exception { + +protected $friendly_message; +protected $about_link; + +public function __construct($message='', $code=0, $previous=null, $friendly_message=null, $about_link=null) { + parent::__construct($message, $code, $previous); + + $this->set_friendly_message($friendly_message); + $this->set_about_link($about_link); +} + +public function set_friendly_message($message) { + $this->friendly_message = $message; +} + +public function set_about_link($link) { + $this->about_link = $link; +} + +public function send_response($content_type=errors::CONTENT_TYPE_OFFICIAL, $encode_options=448, $response=null) { + $jsonapi = new errors($this, $this->friendly_message, $this->about_link); + $jsonapi->send_response($content_type, $encode_options, $response); + exit; +} + +public function __toString() { + $this->send_response(); + return ''; +} + +} From 0e717048558d3a8b1e1e64af1996c05751207f2d Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Fri, 12 Jun 2015 23:43:11 +0200 Subject: [PATCH 02/11] native exceptions can also be used of course --- examples/{errors_exception.php => errors_exception_native.php} | 1 + examples/index.html | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) rename examples/{errors_exception.php => errors_exception_native.php} (98%) diff --git a/examples/errors_exception.php b/examples/errors_exception_native.php similarity index 98% rename from examples/errors_exception.php rename to examples/errors_exception_native.php index 6fcaccc..54e49d4 100644 --- a/examples/errors_exception.php +++ b/examples/errors_exception_native.php @@ -24,4 +24,5 @@ catch (Exception $e) { $jsonapi = new \alsvanzelf\jsonapi\errors($e); $jsonapi->send_response($content_type); + exit; } diff --git a/examples/index.html b/examples/index.html index 9d9ea4d..d4f5a73 100644 --- a/examples/index.html +++ b/examples/index.html @@ -28,8 +28,8 @@

Resources collections

Errors

From ec2b45e4c6bc8c1e9701927540da1292dc30d5f4 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Fri, 12 Jun 2015 23:43:47 +0200 Subject: [PATCH 03/11] adding exceptions w/o exceptions... --- src/errors.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/errors.php b/src/errors.php index a03b9dd..e68b6c6 100644 --- a/src/errors.php +++ b/src/errors.php @@ -189,7 +189,7 @@ public function fill_errors($errors) { * * @todo hide exception meta data on production environments */ -public function add_exception($exception=null, $friendly_message=null, $about_link=null) { +public function add_exception($exception, $friendly_message=null, $about_link=null) { $previous_exception = $exception->getPrevious(); if ($previous_exception) { $this->add_exception($previous_exception); From 6a72d52b769c0f5e2c0f0491eb1948ad35629fdd Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Fri, 12 Jun 2015 23:44:51 +0200 Subject: [PATCH 04/11] hint at the custom exceptions in the readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 5286c65..8e9d185 100644 --- a/README.md +++ b/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. From cf80956d617962d47e372c438f04fce037ea2307 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Wed, 17 Jun 2015 19:55:55 +0200 Subject: [PATCH 05/11] update examples with current master --- examples/errors_exception_direct.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/examples/errors_exception_direct.php b/examples/errors_exception_direct.php index 5beb9ad..7b750c6 100644 --- a/examples/errors_exception_direct.php +++ b/examples/errors_exception_direct.php @@ -8,13 +8,17 @@ /** * 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 = \alsvanzelf\jsonapi\base::STATUS_NOT_FOUND; $friendly_message = 'We don\'t know this user.'; $about_link = 'www.example.com/search'; - throw new \alsvanzelf\jsonapi\exception('unknown user', 404, $previous=null, $friendly_message, $about_link); + throw new \alsvanzelf\jsonapi\exception('unknown user', $http_status, $previous=null, $friendly_message, $about_link); } catch (Exception $e) { echo $e; From e21cc66822dbb10649528f3f0ad03e542208f2f7 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Wed, 17 Jun 2015 22:01:30 +0200 Subject: [PATCH 06/11] update after merging split of base classes --- examples/errors_exception_direct.php | 2 +- src/errors.php | 16 +++------------- src/exception.php | 2 +- 3 files changed, 5 insertions(+), 15 deletions(-) diff --git a/examples/errors_exception_direct.php b/examples/errors_exception_direct.php index 7b750c6..248a371 100644 --- a/examples/errors_exception_direct.php +++ b/examples/errors_exception_direct.php @@ -15,7 +15,7 @@ */ try { - $http_status = \alsvanzelf\jsonapi\base::STATUS_NOT_FOUND; + $http_status = \alsvanzelf\jsonapi\response::STATUS_NOT_FOUND; $friendly_message = 'We don\'t know this user.'; $about_link = 'www.example.com/search'; throw new \alsvanzelf\jsonapi\exception('unknown user', $http_status, $previous=null, $friendly_message, $about_link); diff --git a/src/errors.php b/src/errors.php index b991a74..48b957a 100644 --- a/src/errors.php +++ b/src/errors.php @@ -17,19 +17,9 @@ * - meta data @see ->add_meta() or ->fill_meta() * - self link @see ->set_self_link() * - * @note ease error handling by using a jsonapi\exception - * - * ``` - * try { - * throw new jsonapi\exception('something went wrong'); - * } - * catch (Exception $e) { - * $e->send_response(); - * exit; - * } - * ``` - * - * @see jsonapi\exception::__toString() when you want to use your own exception handling + * @note ease error handling by using a jsonapi\exception instead + * @see examples/errors_exception_direct.php + * @see or jsonapi\exception::__toString() when you want to use your own exception handling */ class errors extends response { diff --git a/src/exception.php b/src/exception.php index 3346a38..309d85c 100644 --- a/src/exception.php +++ b/src/exception.php @@ -29,7 +29,7 @@ public function set_about_link($link) { $this->about_link = $link; } -public function send_response($content_type=errors::CONTENT_TYPE_OFFICIAL, $encode_options=448, $response=null) { +public function send_response($content_type=response::CONTENT_TYPE_OFFICIAL, $encode_options=448, $response=null) { $jsonapi = new errors($this, $this->friendly_message, $this->about_link); $jsonapi->send_response($content_type, $encode_options, $response); exit; From 53825e6d734d2dbc405f252fb9ec28686f809e6e Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Mon, 6 Jul 2015 09:13:52 +0200 Subject: [PATCH 07/11] some more documentation for the custom exception object --- src/exception.php | 58 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 7 deletions(-) diff --git a/src/exception.php b/src/exception.php index 309d85c..3264d9c 100644 --- a/src/exception.php +++ b/src/exception.php @@ -11,30 +11,74 @@ 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 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); - $this->set_friendly_message($friendly_message); - $this->set_about_link($about_link); + if ($friendly_message) { + $this->set_friendly_message($friendly_message); + } + if ($about_link) { + $this->set_about_link($about_link); + } } -public function set_friendly_message($message) { - $this->friendly_message = $message; +/** + * sets a main user facing message + * + * @see error->set_friendly_message() + */ +public function set_friendly_message($friendly_message) { + $this->friendly_message = $friendly_message; } -public function set_about_link($link) { - $this->about_link = $link; +/** + * 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; } -public function send_response($content_type=response::CONTENT_TYPE_OFFICIAL, $encode_options=448, $response=null) { +/** + * 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=448, $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 ''; From 60b226f86bc0d0f14097541bc41caae894cf7467 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Mon, 6 Jul 2015 09:17:55 +0200 Subject: [PATCH 08/11] updates exceptions with upcoming changes in non-error-status branch --- src/exception.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/exception.php b/src/exception.php index 3264d9c..d1f5468 100644 --- a/src/exception.php +++ b/src/exception.php @@ -25,7 +25,7 @@ class exception extends \Exception { * * @param string $message * @param integer $code optional, defaults to 500 - * if using one of the predefined ones in response::STATUS_* + * 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 @@ -67,7 +67,7 @@ public function set_about_link($about_link) { * * @see errors->send_response() */ -public function send_response($content_type=null, $encode_options=448, $response=null) { +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; From 88b99fd5fe3dab835495a00ac87241a1fec1f06f Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Sun, 19 Jul 2015 17:30:59 +0200 Subject: [PATCH 09/11] skip unneeded exit --- examples/errors_exception_native.php | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/errors_exception_native.php b/examples/errors_exception_native.php index 2b12949..d705891 100644 --- a/examples/errors_exception_native.php +++ b/examples/errors_exception_native.php @@ -21,5 +21,4 @@ catch (Exception $e) { $jsonapi = new jsonapi\errors($e); $jsonapi->send_response(); - exit; } From b601ab0ae8cb00fbcf432a5f73b2cc79a92c3a65 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Sun, 19 Jul 2015 17:34:27 +0200 Subject: [PATCH 10/11] tidy up docblocks a bit --- src/errors.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/errors.php b/src/errors.php index e05817e..ec75974 100644 --- a/src/errors.php +++ b/src/errors.php @@ -17,9 +17,9 @@ * - meta data @see ->add_meta() or ->fill_meta() * - self link @see ->set_self_link() * - * @note ease error handling by using a jsonapi\exception instead + * @note ease error handling by using a jsonapi\exception * @see examples/errors_exception_direct.php - * @see or jsonapi\exception::__toString() when you want to use your own exception handling + * @see jsonapi\exception::__toString() when you want to use your own exception handling */ class errors extends response { From 2eacdb93d13d18b2fffedb64608b94f97cfa1066 Mon Sep 17 00:00:00 2001 From: Lode Claassen Date: Sun, 19 Jul 2015 17:39:42 +0200 Subject: [PATCH 11/11] updates exception example with namespacing --- examples/errors_exception_direct.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/examples/errors_exception_direct.php b/examples/errors_exception_direct.php index 248a371..5a42255 100644 --- a/examples/errors_exception_direct.php +++ b/examples/errors_exception_direct.php @@ -1,5 +1,7 @@