Author: Peter Keung
Date: 2007-01-26 23:01:49 +0100 (Fri, 26 Jan 2007)
New Revision: 4585
Log:
Edited the Execution eZ Components tutorial
Modified:
trunk/Execution/docs/tutorial.txt
Modified: trunk/Execution/docs/tutorial.txt
===================================================================
--- trunk/Execution/docs/tutorial.txt 2007-01-25 20:49:18 UTC (rev 4584)
+++ trunk/Execution/docs/tutorial.txt 2007-01-26 22:01:49 UTC (rev 4585)
@@ -1,4 +1,4 @@
-eZ components - Execution
+eZ Components - Execution
~~~~~~~~~~~~~~~~~~~~~~~~~
.. contents:: Table of Contents
@@ -6,48 +6,48 @@
Introduction
============
-If there is a problem with your Web application you do not want that your
-visitors see "Fatal error" messages. Instead you want to be able to show them a
-more friendly page telling them what might be wrong, or what they should do
-when they encounter such an error.
+When there is a problem with your web application, you do not want your
+visitors to see "fatal error" messages. Instead you want to be able to show
+them a more friendly page telling them what might be wrong or what they should
+do when they encounter such an error.
Fatal errors and uncaught exceptions in PHP abort your script, but with this
-component you can add hooks to the shutdown system of PHP. This gives you the
-change to show a user-friendly message.
+component you can add hooks to the shutdown system of PHP. This allows you to
+show more user-friendly error messages.
Class overview
==============
The Execution packages provides the ezcExecution class. This class provides the
-full interface to set up the catching of "fatal" errors. The component also
-provides the ezcExecutionErrorHandler interface that error handlers should
-implement. A basic error handler is supplied through the
+full interface to catch "fatal" errors. The component also
+provides the ezcExecutionErrorHandler interface for implementation by error
+handlers. A basic error handler is supplied through the
ezcExecutionBasicErrorHandler class.
Usage
=====
-When starting your application you need to initialize the ezcExecution class by
-calling ezcExecution::init( $className ). The $className is the name of the
-class that implements your handler. In our first example we simply use the
-default provided handler ezcExecutionBasicErrorHandler. Calling the init()
+Start your application by calling ezcExecution::init( $className ) to
+initialize the ezcExecution class. $className is the name of the
+class that implements your handler. In our first example, we will use the
+default handler ezcExecutionBasicErrorHandler. Calling the init()
method sets up the environment and registers the necessary handlers with PHP.
-Before you exit() or die() from your application you need to signal the
-ezcExecution environment that your application exitted properly. Without this
-signal the handlers assume that your application ended unsuspectedly. In that
-case they will call the onError() method of the class you specified in the
-init() method.
+Before your application quits with exit() or die(), you need to signal to the
+ezcExecution environment that your application exited properly. Without this
+signal, the handlers assume that your application has ended unsuspectedly. The
+onError() method of the class you specified with the init() method will thus be
+called.
-This example shows the most basic usage:
+This is a basic example:
.. include:: tutorial_example_01.php
:literal:
-In line 4 we initialize the environment and in line 6 we signal the environment
-that we have a clean exit. If we would not have done this, then the script
+In line 4, we initialize the environment and in line 6, we signal to the
+environment that we have a clean exit. Otherwise, the script
would have displayed the following message: ::
This application stopped in an unclean way. Please contact the maintainer
@@ -56,34 +56,33 @@
Have a nice day!
-Of course this is just a default message and you most likely want to tune this
-to your needs. To do so you will have to create a new class that implements the
-ezcExecutionErrorHandler interface. You will only have to implement one method:
-onError(). In the next example we create such a class and implement a custom
-notice.
+This is simply the default message and can be customized. To do so, create a
new
+class that implements the ezcExecutionErrorHandler interface. You will only
+have to implement one method: onError(). In the next example, we create such a
+class and implement a custom message:
.. include:: tutorial_example_02.php
:literal:
-In the lines 4-20 we declare our handler class "MyExecutionHandler" which
-implements the ezcExecutionErrorHandler interface. In it's only method
-(onError, line 6-19) we check on line 8 if the error was caused by an uncaught
-Exception. In that case we retrieve the exception's message into the $message
-variable. Otherwise we assign a static value to $message. The $message is the
-displayed in line 17 and 18.
+In lines 4-20, we declare our handler class *MyExecutionHandler*, which
+implements the ezcExecutionErrorHandler interface. Using the onError method, on
+line 8 we check whether the error was caused by an uncaught
+exception. In that case, we insert the exception's message into the $message
+variable. Otherwise, we assign a static value to $message. $message is then
+displayed in lines 17 and 18.
-When you run the above script, you will be presented with the following warning
-(as we threw an exception on line 24 which we didn't catch): ::
+When you run the above script, the following warning is displayed: ::
This application did not succesfully finish its request. The reason was:
Throwing an exception that will not be caught.
-If you comment out line 24 and 26, the result will instead be: ::
+This is due to line 24, where we throw an uncaught exception. If lines 24 and
+26 are commented out, the result will instead be as follows: ::
This application did not succesfully finish its request. The reason was:
Unclean Exit - ezcExecution::cleanExit() was not called.
-More Information
+More information
================
For more information, see the ezcExecution API documentation.
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
