Internals

giwt is a web framework and so it's purpose is to take in a html-requests and create an appropriate html-responses. What happens is a client sends a html-request to the web server which then evaluates the web/index.php and thus gets a html-response which it returns to the client.

Inside the index.php the application base path is set and a Graphit\Core\Dispatcher is created to handle a request based on the configuration (see: app.json). The Dispatcher itself creates a new Kernel instance to hold the current configuration, then processes the request with a RequestHandler and returns the response of the RequestHandler.

Kernel

The Graphit\Core\Kernel is based on an earlier version of the Pimple\Container-class and as thus is a light weighted container class meant for dependency injection. Basically it's used as a registry/config container which provides php classes based on some .json-configuration.

RequestHandlerInterface

Like the name suggeste the RequestHandlerInterfac-interface is an interface for classes which handle requests. The Graphit\Core\RequestHandlerInterface-interface is small and contains only a single method.

public function handleRequest(Request $request);

The handleRequest-method takes a request (Graphit\Core\Request) as input argument and either returns null or a response (Graphit\Core\Response). So a class implementing the RequestHandlerInterface is free to do anything it wants as long as it either returns null or a Response at the end.

Let's have a look at the Graphit\Core\ChainRequestHandler.

ChainRequestHandler

The ChainRequestHandler implements the Graphit\Core\RequestHandlerInterface and handles a request by invoking a chain of Request- and ResponseHandlers (see below).

public function handleRequest(Request $request)
{
  foreach ($this->requestHandler as $handler) {
    $response = $handler->handleRequest($request);
    if ($response) break;
  }

  if ( !$response) {
    throw new \Exception('No RequestHandler produced a Response');
  }

  foreach ($this->responseHandler as $handler) {
    $response = $handler->handleResponse($response, $request);
  }

  return $response;
}

It allows to add RequestHandlers using it's addRequestHandler(RequestHandlerInterface $handler)-method and ResponseHandlers using it's addResponseHandler(ResponseHandlerInterface $handler)-function. Note that for RequestHandlers we stop as soon as a RequestHandler returns not null. For the ResponseHandlers each of them is applied.

Given a ChainRequestHandler we can:

• use multiple RequesHandlers on a request which might just modify the Request-instance.
  • For example:
  • The Graphit\Core\LocaleRequestHandler just sets the '_locale' information in the Request to the default locale and returns null.
  • A LoggingRequestHandler-implementation might just do some logging about the request return null.
• use multiple Requesthandlers which might either modify the Request or return a Response.
  • For example a LoginRequestHandler could be implemented to return a Response which redirects to the user-page or to the login-page depending on whether the authentification was successfull or not. It could also be implemented to only modifies the Request and another RedirectRequestHandler might create the Response.
• use a RequestHandler which always returns a response. The Graphit\Core\ControllerRequestHandler for example calls the associated *Graphit\Core\Controller for the route of the request and returns it's response.
• use ResponseHandlers which adjust the Response.
  • A CookieResponseHandler might set the cookie inside the response.
  • A DebugResponseHandler might add additional data just for debugging.
  • A ChristmasResponseHandler might add additional javascript code to let snowflakes appear in the response.

As you migth imagine there are lots of possibilities on how to use the ChainRequestHandler.

When no custom 'RequestHandler' is given through the configuration the Dispatcher uses the Graphit\Core\DefaultRequestHandler. (see: services.json)

DefaultRequestHandler

The Graphit\Core\DefaultRequestHandler encapsulates and configures a ChainRequestHandler. The ChainRequestHandler is set up to use:

1. A Graphit\Core\LocaleRequestHandler which sets the default and possible locales on the request and returns null. Note that 'de' is used as fallback when no possible and/or default local is set through the services.json.
2. A Graphit\Core\RouterRequestHandler which uses Graphit\Core\Router:match (see: [Router][graphit/giwt/Router.md]) to checks whether a route pattern, given through router.json, matches the route of the request, stores the result inside the request and returns null.
3. A Graphit\Core\PossibleLocaleRequestHandler which checks whether the current locale is either the default locale or one of the possible locales. (see: services.json.md)
4. A Graphit\Core\ControllerRequestHandler which handles a request by invoking the controller associated to the route of the request and returns the Response of the controller. Note: In case the ControllerRequestHandler is not used as one of the RequestHandlers, any _controller-configurations inside the routes.json will do nothing.

ResponseHandlerInterface

Like the RequestHandlerInterface the ResponseHandlerInterface is slim, it only requires the implemtation of the 'handleResponse'-method.

public function handleResponse(Response $response, Request $request);

It takes the response (Graphit\Core\Response) to a request (Graphit\Core\Response) and returns a new or modified response. Again there is a lot of freedom to implement what ever is needed. 'giwt' by default does not use any ResponseHandlers. Here are a few senarios for 'ResponseHandlers':

• Adjusting a repsonse to contain additional information like statistics and debugging depending on the user mentioned in the request.
• Adjusting a response depending on whether the request came from a registered/known user or from an anonymous source.
• Modifying cookies in the response.