PageRenderTime 45ms CodeModel.GetById 23ms RepoModel.GetById 0ms app.codeStats 0ms

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