<commit_before>eZ components - Execution
~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

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.


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.

More Information
================

For more information, see the ezcExecution API documentation.



..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79<commit_msg>Edited the Execution eZ Components tutorial<commit_after>eZ Components - Execution
~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

Introduction
============

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 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 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
=====

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 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 is a basic example:

.. include:: tutorial_example_01.php
   :literal:

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
    of this system and explain him that the system doesn't work properly at the
    moment.

    Have a nice day!

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 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, the following warning is displayed: ::

    This application did not succesfully finish its request. The reason was:
    Throwing an exception that will not be caught.

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
================

For more information, see the ezcExecution API documentation.



..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79
{'fraction_non_alphanumeric': 0.056950483938841355, 'fraction_numerical': 0.007153878524337214, 'mean_word_length': 4.328849028400598, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4180080', 'n_tokens_mistral': 1785, 'n_tokens_neox': 1673, 'n_words': 1049}