## 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. */
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. class ezcExecution
61. {
62. /**
63. * Used for keeping a record whether the ezcExecution mechanism was
64. * initialized through the init() method.
65. * @var bool
66. */
67. static private $isInitialized = false;
69. /**
70. * Contains the name of the class that is going to be used to call the
71. * onError() static method on when an fatal error situation occurs.
72. * @var string
73. */
74. static private $callbackClassName = null;
76. /**
77. * Records whether we had a clean exit from the application or not. If it's
78. * false then the shutdownCallbackHandler() method will not call the
79. * Execution Handler's onError() method.
80. * @var bool
81. */
82. static private $cleanExit = false;
84. /**
85. * A shutdown handler can not be removed, and that's why this static
86. * property records if it was set or not. This ensures that the class will
87. * only set the shutdown handler once over the lifetime of a request.
88. * @var bool
89. */
90. static private $shutdownHandlerRegistered = false;
92. /**
93. * Initializes the ezcExecution environment.
94. *
95. * With this method you initialize the ezcExecution environment. You need
96. * to specify a class name $callBackClassName that will be used to call the
97. * onError() method on in case of an error. The class name that you
98. * pass should implement the ezcExecutionErrorHandler interface. This
99. * method takes care of registering the uncaught exception and shutdown
100. * handlers.
101. *
102. * @throws ezcExecutionInvalidCallbackException if an unknown callback
103. * class was passed.
104. * @throws ezcExecutionWrongClassException if an invalid callback class was
105. * passed.
106. * @throws ezcExecutionAlreadyInitializedException if the environment was
107. * already initialized.
108. *
109. * @param string $callbackClassName
110. * @return void
111. */
112. static public function init ( $callbackClassName )
113. {
114. // Check if the passed classname actually exists
115. if ( ! ezcBaseFeatures :: classExists ( $callbackClassName, true ) )
116. {
117. throw new ezcExecutionInvalidCallbackException ( $callbackClassName );
118. }
120. // Check if the passed classname actually implements the interface.
121. if ( ! in_array ( 'ezcExecutionErrorHandler', class_implements ( $callbackClassName ) ) )
122. {
123. throw new ezcExecutionWrongClassException ( $callbackClassName );
124. }
126. // Check if it was already initialized once
127. if ( self::$isInitialized == true )
128. {
129. throw new ezcExecutionAlreadyInitializedException ();
130. }
132. // Install shutdown handler and exception handler
133. set_exception_handler ( array( 'ezcExecution', 'exceptionCallbackHandler' ) );
134. if ( !self::$shutdownHandlerRegistered )
135. {
136. register_shutdown_function( array( 'ezcExecution', 'shutdownCallbackHandler' ) );
137. }
138. self::$callbackClassName = $callbackClassName;
139. self::$isInitialized = true;
140. self::$cleanExit = false;
141. self::$shutdownHandlerRegistered = true;
142. }
144. /**
145. * Resets the ezcExecution environment.
146. *
147. * With this function you reset the environment. Usually this method should
148. * not be used, but in the cases when you want to restart the environment
149. * this is the method to use. It also takes care of restoring the user
150. * defined uncaught exception handler, but it can not undo the registered
151. * shutdown handler as PHP doesn't provide that functionality.
152. *
153. * @return void
154. */
155. static public function reset ()
156. {
157. if ( self::$isInitialized )
158. {
159. restore_exception_handler();
160. }
161. self::$callbackClassName = null;
162. self::$isInitialized = false;
163. self::$cleanExit = false;
164. }
166. /**
167. * Marks the current application as cleanly-exited.
168. *
169. * With this method you signal the ezcExecution environment that your
170. * application ended without errors. This is usually done just before you
171. * reach the end of your script, or just before you call
172. * {@link http://www.php.net/exit exit()} or
173. * {@link http://www.php.net/die die()}.
174. *
175. * @throws ezcExecutionNotInitializedException if the environment was not
176. * yet initialized.
177. * @return void
178. */
179. static public function cleanExit ()
180. {
181. self::$cleanExit = true;
182. }
184. /**
185. * Handler for uncaught exceptions.
186. *
187. * The ezcExecution environment installs this method as handler for
188. * uncaught exceptions and will be called when one is found. This method's
189. * only function is to call the ::onError() static method of the error
190. * handler set with the init() method. It passes along the uncaught
191. * exception to this method.
192. *
193. * This method has to be public otherwise PHP can not call it, but you
194. * should never call this method yourself.
195. *
196. * @param Exception $e
197. * @return void
198. */
199. static public function exceptionCallbackHandler ( Exception $e )
200. {
201. self::$cleanExit = true;
202. call_user_func ( array( self::$callbackClassName, 'onError' ), $e );
203. }
205. /**
206. * Shutdown handler
207. *
208. * The ezcExecution environment installs this method as general shutdown handler.
209. * This method's only function is to call the ::onError() static method of
210. * the error handler set with the init() method.
211. *
212. * @return void
213. */
214. static public function shutdownCallbackHandler ()
215. {
216. if ( !self::$cleanExit )
217. {
218. self::$cleanExit = true;
219. call_user_func ( array( self::$callbackClassName, 'onError' ) );
220. }
221. }
222. }
223. ?>

Documentation generated by phpDocumentor 1.4.3