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

Runtime modes

mikey179 edited this page Oct 3, 2014 · 5 revisions

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 with four different modes available in the class stubbles\lang\DefaultMode.

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.

  • DefaultMode::prod()
    • uses exception handler stubbles\lang\errorhandler\ProdModeExceptionHandler
    • uses default error handler stubbles\lang\errorhandler\DefaultErrorHandler
    • caching enabled
  • DefaultMode::test()
    • uses exception handler stubbles\lang\errorhandler\DisplayExceptionHandler
    • uses default error handler stubbles\lang\errorhandler\DefaultErrorHandler
    • caching enabled
  • DefaultMode::stage()
    • uses exception handler stubbles\lang\errorhandler\DisplayExceptionHandler
    • no error handler
    • caching disabled
  • DefaultMode::dev()
    • uses exception handler stubbles\lang\errorhandler\DisplayExceptionHandler
    • 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 two parameters: the first is the 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.

Inclusion via IoC

In your applications you should typehint against stubbles\lang\Mode and not refer to any of the concrete mode instances. This will ensure that you refer to the mode selected by your application. To provide the runtime mode via Ioc you may want to use the stubbles\ioc\module\Runtime. You can give it the requested runtime mode as constructor argument - if it is not supplied the binding module will fall back to DefaultMode::prod(). For applications it is advised to create a new binding module which extends from the mode binding module and provides logic for the selection of the appropriate runtime mode.

Create your own mode

By implementing the stubbles\lang\Mode 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:

  • stubbles\lang\errorhandler\ProdModeExceptionHandler will issue a HTTP 500 response with the contents of the file path/to/project/docroot/500.html (if the file is not present it will use a default error message).
  • stubbles\lang\errorhandler\DisplayExceptionHandler displays the exception message and the stack trace of the exception.

Both handlers have logging enabled by default. To switch off logging use $exceptionHandler->disableLogging(). Logged exceptions can be found at path/to/project/log/errors/YYYY/MM/exceptions-YYYY-MM-DD.log.

See PHP manual on exception handlers for more information.

Your own exception handler

You can create your own exception handler by implementing the stubbles\lang\errorhandler\ExceptionHandler interface.

Error handler

For production and test mode Stubbles uses the stubbles\lang\errorhandler\DefaultErrorHandler class. It combines some other error handlers which are executed in the following order:

  • stubbles\lang\errorhandler\IllegalArgumentErrorHandler checks for errors of type E_RECOVERABLE_ERROR and if they denote a hurted type hint. If this is the case a stubbles\lang\exceptions\IllegalArgumentException is thrown.
  • stubbles\lang\errorhandler\LogErrorHandler will log any PHP errors that have not been handled by another error handler. Log files go to path/to/project/log/errors/YYYY/MM/php-error-YYYY-MM-DD.log.

See PHP manual on exception handlers for more information.

Your own error handler

You can create your own exception handler by implementing the stubbles\lang\errorhandler\ErrorHandler interface.

Clone this wiki locally