STDERR MVC API: Handling Errors Into Responses
This revolutionary API elegantly and efficiently handles errors/exceptions that may occur in an application into log reports and server responses using a dialect of MVC paradigm.
How does it work?
This API implements a variation of Model-View-Controller pattern tailor made to fits its design requirements. API logic is bootstrapped by a FrontController class. FrontController's job is to handle exceptions (incl. errors) by sending them to reporters (if any) then issue a HTTP response based on contents of user-defined xml file where your application is set up.
In order to be aligned to the principle of doing nothing more than absolutely required, since most page requests made by users won't throw exceptions, this api runs in two steps:
- instantiation: FrontController is instanced by application bootstrap file. In its constructor it registers itself as sole handlers of PHP errors (normal or fatal) and uncaught exceptions. From that moment on it will lie in dormant mode as request is handled in normal stderr stream, so it only loads the logic necessary for registration.
- handling: when an error or an exception was thrown in stderr stream, handle() method is automatically executed. Only then does API read XML and load all of its dependencies necessary in order to:
- report handled exception to a storage medium (eg: log file)
- display response back to original caller
Instead of implementing handling logic by itself, FrontController delegates to components dedicated to a particular aspect of this process. These components are of two types:
- Fully defined by API, ran by instantiation:
Fundamental components designed to be atomic (usable by themselves):
- Application: Collects immutable data about your application based on content of user-defined xml file
- Request: Collects immutable data about exception handled and <exception> or <exceptions> XML tag that matches it.
- Response: Collects mutable data necessary for response (usually set up by controllers) as well as logic necessary to resolve and display output.
Helper components employed by FrontController:
- ReportersLocator: locates user defined ErrorReporter from "class" attribute of matching <reporter> tag in folder defined by application > paths > reporters tag
- ControllerLocator: locates user defined Controller from "controller" attribute of matching <exception> or <exceptions> tag in folder defined by application > paths > controllers tag
- RendererLocator: locates user defined ErrorRenderer from "class" attribute of matching <renderer> tag in folder defined by application > paths > renderers tag
Optional user-defined components whose blueprints are defined by API:
- ErrorReporter: user-defined classes implementing this interface report errors to a storage medium based on matching <reporter> tags and development environment.
- Controller: user-defined classes extending it perform page controller logic such as interrogating models then sending data to Response based on exception handled
- ErrorRenderer: user-defined classes implementing this interface compile view (response body) into output stream based on response content type and files on disk (eg: templates).
All classes inside API belong to namespace Lucinda\MVC\STDERR! User defined components need not (and should not) use that namespace.
What are the steps taken to issue response to handled exception?
The order in which FrontController performs handling is:
- Redirects its own errors to an user-defined ErrorHandler instance received as constructor argument.
- Constructs Application object based on xml file.
- Constructs Request object based on handled exception.
- Uses ReportersLocator to locate then instances and runs user-defined ErrorReporter classes found.
- Constructs Response object based on Application and Request information.
- If handled exception is associated to a controller, uses ControllerLocator to locate then instances and runs matching user-defined Controller class based on Application, Request and Response objects.
- Uses RendererLocator to locate then instances and runs matching user-defined ErrorRenderer class found.
- Displays response back to caller by running commit() method @ Response object
How can I install and use it?
To learn how to install and use this API, follow this step-by-step guide!