Skip to content
This repository has been archived by the owner on Jan 16, 2019. It is now read-only.

Docs RuntimeModes

Jump to bottom
Frank Kleine edited this page Apr 7, 2012 · 1 revision

Table of Contents

Runtime Modes

Applications often have different runtime modes depending on the environment where they are running. For instance, there may be a mode for the production environment, and this may be different from the mode the application runs in while it is developed. Stubbles supports different runtime modes and makes use of this in some classes, mainly to decide whether data should be cached or not. Currently, there are four different modes available in the class net::stubbles::lang::stubDefaultMode.

The mode instances contain information about which exception handler and which error handler should be used, else well as whether caching is enabled or not.

    • stubDefaultMode::prod()
        • uses exception handler net::stubbles::lang::errorhandler::stubProdModeExceptionHandler
        • uses default error handler net::stubbles::lang::errorhandler::stubDefaultErrorHandler
        • caching enabled
    • stubDefaultMode::test()
        • uses exception handler net::stubbles::lang::errorhandler::stubDisplayExceptionHandler
        • uses default error handler net::stubbles::lang::errorhandler::stubDefaultErrorHandler
        • caching enabled
    • stubDefaultMode::stage()
        • uses exception handler net::stubbles::lang::errorhandler::stubDisplayExceptionHandler
        • no error handler
        • caching disabled
    • stubDefaultMode::dev()
        • uses exception handler net::stubbles::lang::errorhandler::stubDisplayExceptionHandler
        • no error handler
        • caching disabled

While stage and dev mode currently are not different this may change in future in case new mode depending switches become necessary. To change the exception and/or error handler to be used, set the new ones via setExceptionHandler()/setErrorHandler() on the appropriate mode instance. Both methods take three parameters: the first is the full qualified name of the class or an instance of the class that should be used as exception or error handler, the second is the name of the method that should handle the uncatched exception or error, and the last parameter is one of the stubMode::HANDLER_STATIC or stubMode::HANDLER_INSTANCE constants. The first denotes that the handler method must be executed statically while the second denotes that the handler method must be called on an instance of the given class. If the first parameter is a class instance and the third parameter of value stubMode::HANDLER_STATIC a net::stubbles::lang::exceptions::stubIllegalArgumentException will be thrown when the handler is registered. However it is possible to give a class name as first parameter and stubMode::HANDLER_INSTANCE as third parameter, the necessary instance will then be created when the handler is registered.

In your applications you should inject stubMode and not refer to any of the mode instances. This will ensure that you refer to the mode selected by your application. To include the mode selection and registering of error and exception handler you may want to use the net::stubbles::ioc::module::stubModeBindingModule. You can give it the requested runtime mode as constructor argument - if it is not supplied the binding module will fall back to stubDefaultMode::prod().

Create your own mode

By implementing the net::stubbles::lang::stubMode interface you can create your own runtime mode implementation.

More useful methods on mode instances

Every mode instance offers the following methods beside the ones already mentioned above:

    • name() returns the name of the mode (PROD, TEST, STAGE or DEV)
    • isCacheEnabled() returns true if the cache is enabled for this mode and false if not.

Exception handler

Stubbles offers two different exception handlers: net::stubbles::lang::errorhandler::stubProdModeExceptionHandler and net::stubbles::lang::errorhandler::stubDisplayExceptionHandler. The main difference between them is that the stubProdModeExceptionHandler will issue a HTTP 500 response with the contents of the file path/to/stubbles/config/errors/500.html while the stubDisplayExceptionHandler displays the exception message and the stack trace of the exception. See PHP manual on exception handlers for more informations.

Both handlers have logging enabled by default. To switch off logging use $exceptionHandler->setLogging(false). To customize the log target (exception by default) use $exceptionHandler->setLogTarget('new-target'), to set the log level (stubLogger::LEVEL_ERROR by default) use $exceptionHandler->setLogLevel(stubLogger::LEVEL_DEBUG). (See Logging data for more informations about the log target and the log level.)

Error handler

For production and test mode Stubbles uses the net::stubbles::lang::errorhandler::stubDefaultErrorHandler class. This in turn is an instance of the net::stubbles::lang::errorhandler::stubCompositeErrorHandler class and consists of error handlers executed in the following order:

    • net::stubbles::lang::errorhandler::stubIllegalArgumentErrorHandler checks for errors of type E_RECOVERABLE_ERROR and if they denote a hurted type hint. If this is the case a net::stubbles::lang::exceptions::stubIllegalArgumentException is thrown.
    • net::stubbles::lang::errorhandler::stubLogErrorHandler will log any PHP errors that have not been handled by another error handler. To customize the log target (php-error by default) use $errorHandler->setLogTarget('new-target'), to set the log level (stubLogger::LEVEL_ERROR by default) use $errorHandler->setLogLevel(stubLogger::LEVEL_DEBUG). (See Logging data for more informations about the log target and the log level.)

See PHP manual on exception handlers for more informations.

Clone this wiki locally