documented new global exceptions and improved exception handling

chatii · May 19, 2015 · b5abe53 · b5abe53
1 parent adf596d
commit b5abe53
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 4 deletions.
diff --git a/general/error.html b/general/error.html
@@ -196,7 +196,9 @@ <h4 id="throw_500">Throwing a 500</h4>
 				There may be moments where your applications simply need to stop and show an error to
 				indicate that something has gone wrong on the server. Normally this is a
 				<a href="http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_Server_Error">500 Internal
-				Server Error</a>.
+				Server Error</a>. This exception can be caught in the front controller by defining a
+				<kbd>_500_</kbd> route. It allows you to show a proper error message, do additional
+				error logging, or send a notification to an administrator to get the issue fixed.
 			</p>
 
 			<p>
@@ -205,6 +207,21 @@ <h4 id="throw_500">Throwing a 500</h4>
 
 			<pre class="php"><code>throw new HttpServerErrorException;</code></pre>
 
+			<h4 id="throw_403">Throwing a 403</h4>
+
+			<p>
+				If you want centralized handling of access violations, you can choose to signal an
+				access violation by throwing an HttpNoAccessException. This exception can be caught
+				in the front controller by defining a <kbd>_403_</kbd> route. The handler could for
+				example store the current URI, ask for a login, and if a success, return to the stored
+				URI so the user can return to where the violation occured.
+			</p>
+			<p>
+				Similar to throwing a 404, one can throw a 403 error.
+			</p>
+
+			<pre class="php"><code>throw new HttpNoAccessException;</code></pre>
+
 			<h3 id="cli">Errors in CLI mode</h3>
 
 			<p>

diff --git a/general/routing.html b/general/routing.html
@@ -52,14 +52,25 @@ <h2>Routing</h2>
 
 			<h3 id="reserved">Reserved Routes</h3>
 
-			<p>In Fuel there are 2 reserved routes.	 They are <kbd>_root_</kbd> and <kbd>_404_</kbd>.</p>
+			<p>In Fuel there are 4 reserved routes.	 They are <kbd>_root_</kbd>, <kbd>_403_</kbd>, <kbd>_404_</kbd> and <kbd>_500_</kbd>.</p>
 
 			<ul>
 				<li><kbd>_root_</kbd> - The default route when no URI is specified.</li>
-				<li><kbd>_404_</kbd> - The route used when no controller or action can be found. Can also be used as a
-					catch-all route.</li>
+				<li><kbd>_403_</kbd> - The route used when the application throws an HttpNoAccessException that isn't caught.</li>
+				<li><kbd>_404_</kbd> - The route used when the application throws an HttpNotFoundException that isn't caught.</li>
+				<li><kbd>_500_</kbd> - The route used when the application throws an HttpServerErrorException that isn't caught.</li>
 			</ul>
 
+			<p class="note">
+				The request class throws an HttpNotFoundException when you request a URI (a route) that your application
+				can't resolve.
+			</p>
+			<p class="note">
+				If no <kbd>_404_</kbd> route is defined, the framework uses it's own error handler to display
+				a "page not found" message. If no <kbd>_403_</kbd> or <kbd>_500_</kbd> route is defined, these
+				exceptions remain uncaught, and are handled like any other exception your application might throw.
+			</p>
+
 			<pre class="php"><code>return array(
     '_root_'  => 'welcome/index',
     '_404_'   => 'welcome/404',