Application init

Scope of this document

This document covers the information on how a preconfigured application prepares the incoming request and passes it to the MVC application stack.

Application flow

A normal approach to a design of the front-controller is to configure the application and then wrap the environment with classes to provide an object-oriented API to request and response (see the IWebContext contract). This unifies and simplifies further development of the MVC stack which actually handles the request.

A wrapped request then can be passed to the MVC stack, where various routers/filters/actions may be applied to handle the request and produce the response.

The problem is that PHP is a scripting language, and there are various things you cannot check at compile time. At that time you need an application that can handle unexpected issues.

There is a SiteApplication class that helps your applications to be more stable and predictable. It does the following:

accepts the instance of an IRouter that will look up for appropriate request handler
wraps a standard incoming PHP request with the corresponding classes:
- $_SERVER is wrapped with WebServerState
- $_GET, $_POST, $_COOKIE and $_FILES are wrapped with WebRequest
- an object of WebResponse class representing response is instantiated
- WebRequest, WebResponse and WebServerState are then wrapped with WebContext
defines a handler for 404 error which is triggered when the router fails to find the route that corresponds the request. By default this handler takes the fallback route defined by the router and invokes it. You can overwrite SiteApplication::handle404() to customize the logic.
defines a handler for 500 error which occurs when your application flow is terminated because of unexpected and unhanded PHP error. By default this handler sends a crash dump to email defined by the BUGS_EMAIL constant and prints a stack trace. You can overwrite the failover stub SiteApplication::handle500() to customize the logic.
finally forces the router to look up the routes table for the route that corresponds the incoming request, and invokes the attached dispatcher to handle the request (learn more).

So the SiteApplication does all dirty work for you. All you need is to invoke it in your front-controller:

index.php


//
// load the configuration files here
//

$application = new SiteApplication(new MyRouter);
$application->run();

Best practices

We strongly recommend you to create your own SiteApplication extending the base class, and separate front-controllers that should produce responses of different types. For example, developing an AJAX web-service you may define two front-controllers. The first one is index.php may use the standard SiteApplication while another one front-controller, say, ajax.php, uses a custom SiteApplication which defines the error handler that handles unexpected errors and produces the result in AJAX-compliant format:

class AjaxSiteApplication extends SiteApplication {
	protected function handle500(Exception $e) {
		echo json_encode(array(
			'error' => $e->getCode()
		));
		
		$this->notify500(BUGS_EMAIL, $e);
	}
}

Conclusion