Author: Derick Rethans Date: 2006-01-23 23:23:32 +0100 (Mon, 23 Jan 2006) New Revision: 2010
Log: - Added Execution tutorial. Added: packages/Execution/trunk/docs/tutorial.txt packages/Execution/trunk/docs/tutorial_autoload.php packages/Execution/trunk/docs/tutorial_example_01.php packages/Execution/trunk/docs/tutorial_example_02.php Added: packages/Execution/trunk/docs/tutorial.txt =================================================================== --- packages/Execution/trunk/docs/tutorial.txt 2006-01-23 22:23:07 UTC (rev 2009) +++ packages/Execution/trunk/docs/tutorial.txt 2006-01-23 22:23:32 UTC (rev 2010) @@ -0,0 +1,101 @@ +eZ components - Execution +~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +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. + + +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 +ezcExecutionBasicErrorHandler class. + + +Installation +============ + +This tutorial assumes that you have set-up an eZ components environment. For +information on how to do this, please refer to the `Components Introduction`_. + +.. _Components Introduction: http://ez.no/community/articles/an_introduction_to_ez_components + + +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() +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. + +This example shows the most basic usage: + +.. 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 +would have displayed the following message: :: + + This application stopped in an unclean way. Please contact the maintainer + of this system and explain him that the system doesn't work properly at the + moment. + + 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. + +.. 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. + +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): :: + + 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 application did not succesfully finish its request. The reason was: + Unclean Exit - ezcExecution::cleanExit() was not called. + +For more information, see the ezcExecution API documentation. + + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Property changes on: packages/Execution/trunk/docs/tutorial.txt ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Execution/trunk/docs/tutorial_autoload.php =================================================================== --- packages/Execution/trunk/docs/tutorial_autoload.php 2006-01-23 22:23:07 UTC (rev 2009) +++ packages/Execution/trunk/docs/tutorial_autoload.php 2006-01-23 22:23:32 UTC (rev 2010) @@ -0,0 +1,23 @@ +<?php + +require_once 'Base/trunk/src/base.php'; + +/** + * Autoload ezc classes + * + * @param string $class_name + */ +function __autoload( $class_name ) +{ + if ( ezcBase::autoload( $class_name ) ) + { + return; + } + if ( strpos( $class_name, '_' ) !== false ) + { + $file = str_replace( '_', '/', $class_name ) . '.php'; + require_once( $file ); + } +} + +?> Property changes on: packages/Execution/trunk/docs/tutorial_autoload.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Execution/trunk/docs/tutorial_example_01.php =================================================================== --- packages/Execution/trunk/docs/tutorial_example_01.php 2006-01-23 22:23:07 UTC (rev 2009) +++ packages/Execution/trunk/docs/tutorial_example_01.php 2006-01-23 22:23:32 UTC (rev 2010) @@ -0,0 +1,7 @@ +<?php +require_once 'tutorial_autoload.php'; + +ezcExecution::init( 'ezcExecutionBasicErrorHandler' ); + +ezcExecution::cleanExit(); +?> Property changes on: packages/Execution/trunk/docs/tutorial_example_01.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/Execution/trunk/docs/tutorial_example_02.php =================================================================== --- packages/Execution/trunk/docs/tutorial_example_02.php 2006-01-23 22:23:07 UTC (rev 2009) +++ packages/Execution/trunk/docs/tutorial_example_02.php 2006-01-23 22:23:32 UTC (rev 2010) @@ -0,0 +1,27 @@ +<?php +require_once 'tutorial_autoload.php'; + +class MyExecutionHandler implements ezcExecutionErrorHandler +{ + public static function onError( Exception $e = NULL ) + { + if ( !is_null( $e ) ) + { + $message = $e->getMessage(); + } + else + { + $message = "Unclean Exit - ezcExecution::cleanExit() was not called."; + } + + echo "This application did not succesfully finish its request. " . + "The reason was:\n$message\n\n"; + } +} + +ezcExecution::init( 'MyExecutionHandler' ); + +throw new Exception( "Throwing an exception that will not be caught." ); + +ezcExecution::cleanExit(); +?> Property changes on: packages/Execution/trunk/docs/tutorial_example_02.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
