PageRenderTime 7ms CodeModel.GetById 2ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 1ms

/docs/guide/topics.error.txt

https://bitbucket.org/penkoh/yii
Plain Text | 160 lines | 130 code | 30 blank | 0 comment | 0 complexity | 61e9a67a2acc6f9bbffc1415801d577e MD5 | raw file
  1Error Handling
  2==============
  3
  4Yii provides a complete error handling framework based on the PHP 5
  5exception mechanism. When the application is created to handle an incoming
  6user request, it registers its [handleError|CApplication::handleError]
  7method to handle PHP warnings and notices; and it registers its
  8[handleException|CApplication::handleException] method to handle uncaught
  9PHP exceptions. Consequently, if a PHP warning/notice or an uncaught
 10exception occurs during the application execution, one of the error
 11handlers will take over the control and start the necessary error handling
 12procedure.
 13
 14> Tip: The registration of error handlers is done in the application's
 15constructor by calling PHP functions
 16[set_exception_handler](http://www.php.net/manual/en/function.set-exception-handler.php)
 17and [set_error_handler](http://www.php.net/manual/en/function.set-error-handler.php).
 18If you do not want Yii to handle the errors and exceptions, you may define
 19constant `YII_ENABLE_ERROR_HANDLER` and `YII_ENABLE_EXCEPTION_HANDLER` to
 20be false in the [entry script](/doc/guide/basics.entry).
 21
 22By default, [handleError|CApplication::handleError] (or
 23[handleException|CApplication::handleException]) will raise an
 24[onError|CApplication::onError] event (or
 25[onException|CApplication::onException] event). If the error (or exception)
 26is not handled by any event handler, it will call for help from the
 27[errorHandler|CErrorHandler] application component.
 28
 29Raising Exceptions
 30------------------
 31
 32Raising exceptions in Yii is not different from raising a normal PHP
 33exception. One uses the following syntax to raise an exception when needed:
 34
 35~~~
 36[php]
 37throw new ExceptionClass('ExceptionMessage');
 38~~~
 39
 40Yii defines three exception classes: [CException], [CDbException] and
 41[CHttpException]. [CException] is a generic exception class. [CDbException]
 42represents an exception that is caused by some DB-related operations.
 43[CHttpException] represents an exception that should be displayed to end users
 44and carries a [statusCode|CHttpException::statusCode] property representing an HTTP
 45status code. The class of an exception determines how it should be
 46displayed, as we will explain next.
 47
 48> Tip: Raising a [CHttpException] exception is a simple way of reporting
 49errors caused by user misoperation. For example, if the user provides an
 50invalid post ID in the URL, we can simply do the following to show a 404
 51error (page not found):
 52~~~
 53[php]
 54// if post ID is invalid
 55throw new CHttpException(404,'The specified post cannot be found.');
 56~~~
 57
 58Displaying Errors
 59-----------------
 60
 61When an error is forwarded to the [CErrorHandler] application component,
 62it chooses an appropriate view to display the error. If the error is meant
 63to be displayed to end users, such as a [CHttpException], it will use a
 64view named `errorXXX`, where `XXX` stands for the HTTP status code (e.g.
 65400, 404, 500). If the error is an internal one and should only be
 66displayed to developers, it will use a view named `exception`. In the
 67latter case, complete call stack as well as the error line information will
 68be displayed.
 69
 70> Info: When the application runs in [production
 71mode](/doc/guide/basics.entry#debug-mode), all errors including those internal
 72ones will be displayed using view `errorXXX`. This is because the call
 73stack of an error may contain sensitive information. In this case,
 74developers should rely on the error logs to determine what is the real
 75cause of an error.
 76
 77[CErrorHandler] searches for the view file corresponding to a view in the
 78following order:
 79
 80   1. `WebRoot/themes/ThemeName/views/system`: this is the `system` view
 81directory under the currently active theme.
 82
 83   2. `WebRoot/protected/views/system`: this is the default `system` view
 84directory for an application.
 85
 86   3. `yii/framework/views`: this is the standard system view directory
 87provided by the Yii framework.
 88
 89Therefore, if we want to customize the error display, we can simply create
 90error view files under the system view directory of our application or
 91theme. Each view file is a normal PHP script consisting of mainly HTML
 92code. For more details, please refer to the default view files under the
 93framework's `view` directory.
 94
 95
 96Handling Errors Using an Action
 97-------------------------------
 98
 99Yii allows using a [controller action](/doc/guide/basics.controller#action)
100to handle the error display work. To do so, we should configure the error handler
101in the application configuration as follows:
102
103~~~
104[php]
105return array(
106	......
107	'components'=>array(
108		'errorHandler'=>array(
109			'errorAction'=>'site/error',
110		),
111	),
112);
113~~~
114
115In the above, we configure the [CErrorHandler::errorAction] property to be the route
116`site/error` which refers to the `error` action in `SiteController`. We may use a different
117route if needed.
118
119We can write the `error` action like the following:
120
121~~~
122[php]
123public function actionError()
124{
125	if($error=Yii::app()->errorHandler->error)
126		$this->render('error', $error);
127}
128~~~
129
130In the action, we first retrieve the detailed error information from [CErrorHandler::error].
131If it is not empty, we render the `error` view together with the error information.
132The error information returned from [CErrorHandler::error] is an array with the following fields:
133
134 * `code`: the HTTP status code (e.g. 403, 500);
135 * `type`: the error type (e.g. [CHttpException], `PHP Error`);
136 * `message`: the error message;
137 * `file`: the name of the PHP script file where the error occurs;
138 * `line`: the line number of the code where the error occurs;
139 * `trace`: the call stack of the error;
140 * `source`: the context source code where the error occurs.
141
142> Tip: The reason we check if [CErrorHandler::error] is empty or not is because
143the `error` action may be directly requested by an end user, in which case there is no error.
144Since we are passing the `$error` array to the view, it will be automatically expanded
145to individual variables. As a result, in the view we can access directly the variables such as
146`$code`, `$type`.
147
148
149Message Logging
150---------------
151
152A message of level `error` will always be logged when an error occurs. If
153the error is caused by a PHP warning or notice, the message will be logged
154with category `php`; if the error is caused by an uncaught exception, the
155category would be `exception.ExceptionClassName` (for [CHttpException] its
156[statusCode|CHttpException::statusCode] will also be appended to the
157category). One can thus exploit the [logging](/doc/guide/topics.logging)
158feature to monitor errors happened during application execution.
159
160<div class="revision">$Id$</div>