Download the PHP package / without Composer

All classes inside belong to Lucinda\STDERR namespace!

Configuration

To configure this API you must have a XML with following tags inside:

• application: (mandatory) configures handling on general application basis
• display_errors: (optional) configures whether or not errors should be displayed
• reporters: (optional) configures how your application will report handled error/exception
• resolvers: (mandatory) configures formats in which your application is able to resolve responses to a handled error/exception
• routes: (mandatory) configures error/exception based routing to controllers/views

Application

Tag documentation is completely covered by inherited Abstract MVC API specification! Since STDIN for this API is made of handled throwables but there is no generic throwable value of default_route attribute must be default.

Display_Errors

Maximal syntax of this tag is:

Most of tag logic is already covered by Abstract MVC API specification. Following extra sub-tags/attributes are defined:

• display_errors: (optional) holds whether or not handled error/exception details will be exposed back to callers based on:
  • {ENVIRONMENT}: name of development environment (to be replaced with "local", "dev", "live", etc). {VALUE} can be:
    • 1: indicates error/exception details will be displayed to caller
    • 0: indicates error/exception details won't be displayed to caller

If no display_errors is defined or no {ENVIRONMENT} subtag is found matching current development environment, value 0 is assumed (\Throwable details won't be exposed)!

Tag example:

Reporters

Maximal syntax of this tag is:

Where:

• reporters: (mandatory) holds settings to configure your application for error reporting based on:
  • {ENVIRONMENT}: (mandatory) name of development environment (to be replaced with "local", "dev", "live", etc). Holds one or more reporters, each defined by a tag:
    • reporter: (mandatory) configures an error/exception reporter based on attributes:
      • class: (mandatory) name of user-defined PS-4 autoload compliant class (including namespace) that will report \Throwable.
        Class must be a Reporter instance!
      • {OPTIONS}: a list of extra attributes necessary to configure respective reporter identified by class above

Tag example:

Resolvers

Tag documentation is completely covered by inherited Abstract MVC API specification!

Routes

Maximal syntax of this tag is:

Most of tag logic is already covered by Abstract MVC API specification. Following extra observations need to be made:

• id: (mandatory) mapped error/exception class name or default (matching default_route @ \Throwable instance!
• controller: (optional) name of user-defined PS-4 autoload compliant class (including namespace) that will mitigate requests and responses based on models.
  Class must be a Controller instance!
• error_type: (mandatory) defines default exception/error originator. Must match one of ErrorType enum cases values! Example: "LOGICAL"
• http_status: (mandatory) defines default response HTTP status. Must be a valid HTTP status code! Example: "500"

Tag example:

If handled \Throwable matches no route, default route is used!

Binding Points

In order to remain flexible and achieve highest performance, API takes no more assumptions than those absolutely required! It offers developers instead an ability to bind to its prototypes in order to gain certain functionality.

Declarative Binding

It offers developers an ability to bind declaratively to its prototype classes/interfaces via XML:

Programmatic Binding

It offers developers an ability to bind programmatically to its prototypes via FrontController constructor:

Execution

Initialization

Now that developers have finished setting up XML that configures the API, they are finally able to initialize it by instantiating FrontController.

As a handler of \Throwable instances, above needs to implement FrontController comes with following public methods, all related to initialization process:

Where:

• $documentDescriptor: relative location of XML configuration file. Example: "configuration.xml"
• $developmentEnvironment: name of development environment (to be replaced with "local", "dev", "live", etc) to be used in deciding how to report or whether or not to expose handled \Throwable
• $includePath: absolute location of your project root (necessary because sometimes include paths are lost when errors are thrown). Example: DIR
• $emergencyHandler: a FrontController's handle method
• $displayFormat: value of display format, matching to a format attribute of a resolver @ resolvers XML tag

Very important to notice that once handlers are registered, API employs Aspect Oriented Programming concepts to listen asynchronously for error events then triggering handler automatically. So once API is initialized, you can immediately start your preferred framework that handles http requests to responses!

Handling

Once a \Throwable event has occurred inside STDOUT request-response phase, handle method of FrontController is called. This:

• registers handler presented as constructor argument to capture any error that might occur while handling
• constructs a Application object based on XML where API is configured and development environment
• detects \Throwable handled
• constructs a Application\Route above
• constructs a list of reporters tag @ XML matching development environment
• if found, for each \Throwable to respective medium
• detects Lucinda\MVC\Application\Format matching default_format attribute application tag @ XML or the one manually set via setDisplayFormat method
• constructs a \Lucinda\MVC\Response object based on all objects detected above
• detects routes tag @ XML
• if found, it executes Controller's run method in order to manipulate response
• if \Lucinda\MVC\Response doesn't have a body yet
  • constructs a \Lucinda\MVC\ViewResolver object based on matching resolver tag @ XML and objects detected above. This will, for example, convert templates to a full response body.
  • if not found, program exits with error, otherwise it executes \Lucinda\MVC\ViewResolver's run method in order to convert view to a response body
• calls commit method of \Lucinda\MVC\Response to send back response to caller

All components that are in developers' responsibility (\Lucinda\MVC\Runnable interface.

Installation

First choose a folder, then write this command there using console:

Then create a configuration.xml file holding configuration settings (see initialization above) in project root with following code:

Example of emergency handler:

Unit Tests

For tests and examples, check following files/folders in API sources:

• test.php: runs unit tests in console
• unit-tests.xml: sets up unit tests and mocks "loggers" tag
• tests: unit tests for classes from src folder

Reference Guide

These classes are fully implemented by API:

• configuration XML file and encapsulates information inside
  • \Throwable handled
• Application\Route

These abstract classes require to be extended by developers in order to gain an ability:

• \Throwable reporting
• \Throwable

Class Application

Class Application extends Lucinda\MVC\Application and adds one method relevant to developers:

Class Application Route

Class Application\Route extends Lucinda\MVC\Application\Route and adds following public methods:

Class Request

Class Request encapsulates handled \Throwable and matching Application\Route. It defines following public methods relevant to developers:

Interface ErrorHandler

Interface ErrorHandler contains blueprint for handling \Throwable via method:

Usage example:

https://github.com/aherne/lucinda-framework/blob/master/src/EmergencyHandler.php

Abstract Class Reporter

Abstract class Reporter implements \Lucinda\MVC\Runnable and encapsulates a single \Throwable reporter. It defines following public method relevant to developers:

Developers need to implement run method for each reporter, where they are able to access following protected fields injected by API via constructor:

Usage example:

https://github.com/aherne/lucinda-framework-engine/blob/master/src/AbstractReporter.php https://github.com/aherne/lucinda-framework/blob/master/src/Reporters/File.php

For more info how reporters are detected, check How Are Reporters Located section below!

Abstract Class Controller

Abstract class Controller implements \Lucinda\MVC\Runnable) to set up response (views in particular) based on information detected beforehand. It defines following public method relevant to developers:

Developers need to implement run method for each controller, where they are able to access following protected fields injected by API via constructor:

Usage example:

https://github.com/aherne/lucinda-framework/blob/master/src/Controllers/SecurityPacket.php

For more info how controllers are detected, check How Are Controllers Located section below!

Specifications

Since this API works on top of Abstract MVC API specifications it follows their requirements and adds extra ones as well:

• How Is Response Format Detected
• How Are View Resolvers Located
• How Is Route Detected
• How Are Controllers Located
• How Are Reporters Located
• How Are Views Located

How Is Response Format Detected

This follows parent API specifications only that routes are detected based on \Throwable handled. One difference is that detected value can be overridden using setDisplayFormat method (see Initialization).

How Are View Resolvers Located

This follows parent API specifications in its entirety.

How Is Route detected

This follows parent API specifications only that routes are detected based on \Throwable handled. Let's take this XML for example:

There will be following situations for above:

How Are Controllers Located

This follows parent API specifications only that class defined as controller attribute in Controller.

How Are Reporters Located

To better understand how class attributes @ reporter tags matching development environment, let's take this XML for example:

In that case if "psr-4" attribute in composer.json associates "Lucinda\Project\" with "src/" folder then:

All classes referenced above must be instance of Reporter!

How Are Views Located

This follows parent API specifications in its entirety. Extension is yet to be decided, since it depends on type of view resolved!