Apache Zeta Components Manual :: File Source for execution.php

Source for file execution.php

Documentation is available at execution.php

  1. <?php
  2. /**
  3.  *
  4.  * Licensed to the Apache Software Foundation (ASF) under one
  5.  * or more contributor license agreements.  See the NOTICE file
  6.  * distributed with this work for additional information
  7.  * regarding copyright ownership.  The ASF licenses this file
  8.  * to you under the Apache License, Version 2.0 (the
  9.  * "License"); you may not use this file except in compliance
  10.  * with the License.  You may obtain a copy of the License at
  11.  * 
  12.  *   http://www.apache.org/licenses/LICENSE-2.0
  13.  * 
  14.  * Unless required by applicable law or agreed to in writing,
  15.  * software distributed under the License is distributed on an
  16.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17.  * KIND, either express or implied.  See the License for the
  18.  * specific language governing permissions and limitations
  19.  * under the License.
  20.  *
  21.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  22.  * @version //autogentag//
  23.  * @filesource
  24.  * @package Execution
  25.  */
  26.  
  27. /**
  28.  * Class for handling fatal errors
  29.  *
  30.  * This class allows you to invoke a handler whenever a fatal error occurs, or
  31.  * when an uncatched exception happens.  You can specify which callback
  32.  * function to use and signal whether your application cleanly exited.
  33.  *
  34.  * Example:
  35.  * <code>
  36.  * <?php
  37.  * class myExecutionHandler extends ezcExecutionBasicErrorHandler
  38.  * {
  39.  *     public static function onError( Exception $exception = null )
  40.  *     {
  41.  *         echo "Error!\n";
  42.  *         // If you want, you can use the parent's onError method, but that
  43.  *         // will only show a standard message.
  44.  *         parent::onError( $exception );
  45.  *     }
  46.  * }
  47.  * 
  48.  * ezcExecution::init( 'myExecutionHandler' );
  49.  * 
  50.  * // ....
  51.  * 
  52.  * ezcExecution::cleanExit();
  53.  * ?>
  54.  * </code>
  55.  *
  56.  * @package Execution
  57.  * @version //autogentag//
  58.  * @mainclass
  59.  */
  60. {
  61.     /**
  62.      * Used for keeping a record whether the ezcExecution mechanism was
  63.      * initialized through the init() method.
  64.      * @var bool 
  65.      */
  66.     static private $isInitialized false;
  67.  
  68.     /**
  69.      * Contains the name of the class that is going to be used to call the
  70.      * onError() static method on when an fatal error situation occurs.
  71.      * @var string 
  72.      */
  73.     static private $callbackClassName null;
  74.  
  75.     /**
  76.      * Records whether we had a clean exit from the application or not. If it's
  77.      * false then the shutdownCallbackHandler() method will not call the
  78.      * Execution Handler's onError() method.
  79.      * @var bool 
  80.      */
  81.     static private $cleanExit false;
  82.  
  83.     /**
  84.      * A shutdown handler can not be removed, and that's why this static
  85.      * property records if it was set or not. This ensures that the class will
  86.      * only set the shutdown handler once over the lifetime of a request.
  87.      * @var bool 
  88.      */
  89.     static private $shutdownHandlerRegistered false;
  90.  
  91.     /**
  92.      * Initializes the ezcExecution environment.
  93.      *
  94.      * With this method you initialize the ezcExecution environment. You need
  95.      * to specify a class name $callBackClassName that will be used to call the
  96.      * onError() method on in case of an error. The class name that you
  97.      * pass should implement the ezcExecutionErrorHandler interface. This
  98.      * method takes care of registering the uncaught exception and shutdown
  99.      * handlers.
  100.      *
  101.      * @throws ezcExecutionInvalidCallbackException if an unknown callback
  102.      *          class was passed.
  103.      * @throws ezcExecutionWrongClassException if an invalid callback class was
  104.      *          passed.
  105.      * @throws ezcExecutionAlreadyInitializedException if the environment was
  106.      *          already initialized.
  107.      *
  108.      * @param string $callbackClassName 
  109.      * @return void 
  110.      */
  111.     static public function init$callbackClassName )
  112.     {
  113.         // Check if the passed classname actually exists
  114.         if !ezcBaseFeatures::classExists$callbackClassNametrue ) )
  115.         {
  116.             throw new ezcExecutionInvalidCallbackException$callbackClassName );
  117.         }
  118.  
  119.         // Check if the passed classname actually implements the interface.
  120.         if !in_array'ezcExecutionErrorHandler'class_implements$callbackClassName ) ) )
  121.         {
  122.             throw new ezcExecutionWrongClassException$callbackClassName );
  123.         }
  124.  
  125.         // Check if it was already initialized once
  126.         if self::$isInitialized == true )
  127.         {
  128.             throw new ezcExecutionAlreadyInitializedException();
  129.         }
  130.  
  131.         // Install shutdown handler and exception handler
  132.         set_exception_handlerarray'ezcExecution''exceptionCallbackHandler' ) );
  133.         if !self::$shutdownHandlerRegistered )
  134.         {
  135.             register_shutdown_functionarray'ezcExecution''shutdownCallbackHandler' ) );
  136.         }
  137.         self::$callbackClassName $callbackClassName;
  138.         self::$isInitialized true;
  139.         self::$cleanExit false;
  140.         self::$shutdownHandlerRegistered true;
  141.     }
  142.  
  143.     /**
  144.      * Resets the ezcExecution environment.
  145.      *
  146.      * With this function you reset the environment. Usually this method should
  147.      * not be used, but in the cases when you want to restart the environment
  148.      * this is the method to use. It also takes care of restoring the user
  149.      * defined uncaught exception handler, but it can not undo the registered
  150.      * shutdown handler as PHP doesn't provide that functionality.
  151.      *
  152.      * @return void 
  153.      */
  154.     static public function reset()
  155.     {
  156.         if self::$isInitialized )
  157.         {
  158.             restore_exception_handler();
  159.         }
  160.         self::$callbackClassName null;
  161.         self::$isInitialized false;
  162.         self::$cleanExit false;
  163.     }
  164.  
  165.     /**
  166.      * Marks the current application as cleanly-exited.
  167.      *
  168.      * With this method you signal the ezcExecution environment that your
  169.      * application ended without errors. This is usually done just before you
  170.      * reach the end of your script, or just before you call
  171.      * {@link http://www.php.net/exit exit()} or
  172.      * {@link http://www.php.net/die die()}.
  173.      *
  174.      * @throws ezcExecutionNotInitializedException if the environment was not
  175.      *          yet initialized.
  176.      * @return void 
  177.      */
  178.     static public function cleanExit()
  179.     {
  180.         self::$cleanExit true;        
  181.     }
  182.  
  183.     /**
  184.      * Handler for uncaught exceptions.
  185.      *
  186.      * The ezcExecution environment installs this method as handler for
  187.      * uncaught exceptions and will be called when one is found.  This method's
  188.      * only function is to call the ::onError() static method of the error
  189.      * handler set with the init() method. It passes along the uncaught
  190.      * exception to this method.
  191.      *
  192.      * This method has to be public otherwise PHP can not call it, but you
  193.      * should never call this method yourself.
  194.      *
  195.      * @param Exception $e 
  196.      * @return void 
  197.      */
  198.     static public function exceptionCallbackHandlerException $e )
  199.     {
  200.         self::$cleanExit true;        
  201.         call_user_funcarrayself::$callbackClassName'onError' )$e );
  202.     }
  203.  
  204.     /**
  205.      * Shutdown handler
  206.      *
  207.      * The ezcExecution environment installs this method as general shutdown handler.
  208.      * This method's only function is to call the ::onError() static method of
  209.      * the error handler set with the init() method.
  210.      *
  211.      * @return void 
  212.      */
  213.     static public function shutdownCallbackHandler()
  214.     {
  215.         if !self::$cleanExit )
  216.         {
  217.             self::$cleanExit true;        
  218.             call_user_funcarrayself::$callbackClassName'onError' ) );
  219.         }
  220.     }
  221. }
  222. ?>
Documentation generated by phpDocumentor 1.4.3