Documentation: In Depth Framework & APIs Guide

Lucinda was designed as an XML-based integration platform of APIs knowing nothing of the other, holding single responsibility in an ability they offer to a web application. Integration consists in redirecting all requests to framework, starting MVC APIs based on XMLs they require and binding them to other APIs and developers code in order to produce a response:

Architecture

Framework's job is achieved through an interplay of three independent APIs designed to further modularity and ease of update:

Name Description
Framework Skeleton API Implements "mobile" part of framework logic, the project skeleton developers will start working on once framework was installed. Once installed, composer won't update it! GitHub
Framework Engine API Implements "fixed" part of framework logic, from binding classes required in APIs conversation as well as general purpose classes. Code inside is updatable via composer! GitHub
Framework Configurer API Implements console step-by-step configurer as well as files going to be copied on developers' project once process completes. Code inside is updatable via composer! GitHub

When composer create-project is called, Framework Skeleton API will form your project foundation. It bootstraps all requests to your project to be handled by index.php file, where MVC APIs for STDOUT/STDERR flows are started based on an XML file that configures them:

Name Description XML
STDOUT MVC API MVC engine behind STDOUT framework, handling http(s) requests into responses stdout.xml GitHub
STDERR MVC API MVC engine behind STDERR framework, handling uncaught Throwables into responses stderr.xml GitHub

Above MVC APIs offer a number of binding points, both programmatically (via extension) and declaratively (via XML), where developers can hook to. Framework uses them to integrate other APIs, each adding an extra ability for your site (since only MVC abilities are preinstalled):

Name Ability Added
View Language API templating HTML views using a language extending HTML standard GitHub
Logging API logging messages or errors to a storage medium GitHub
Web Security API performing authentication and authorization GitHub
OAuth2 Client API querying OAuth2 providers, hiding vendor complexity underneath GitHub
SQL Data Access API querying SQL databases, hiding vendor complexity underneath GitHub
NoSQL Data Access API querying NoSQL key-value stores, hiding vendor complexity underneath GitHub
HTTP Headers API reading/writing HTTP headers and performing automatic cache/CORS validation GitHub
Internationalization API automatic internationalization & localization of responses GitHub

The whole integration process is automated by Framework Configurer API, which offers you a step-by-step console program where developers can choose the features they want in their project and program will handle all the configuration complexities.

Components

As above flowchart shows, framework skeleton (components in blue and colored arrows) is extremely light weight, designed in such as way that harmony, minimalism and efficiency are rigurously kept. It is thus nothing more than a glueing layer with four logical components:

Once deployed, skeleton becomes your project foundation, so developers are expected to build upon each of the four components listed:

To learn more what developers can achieve, check Tutorials section!

index.php

Once framework is installed, all requests to your project, except those pointing to static files (eg: public folder), will be bootstrapped to file, whose only job is to start the framework and manage your application in following steps:

Logical schema:

stderr.xml

This file is required to configure STDERR MVC API as well as providing an integration platform of other APIs via following tags:

Logical schema:

Developers can use different bindings from those provided by framework (components in red above), provided their class extends required prototype and lies in required folder:

XML Tag Tag Attribute Class Prototype Folder
class application/reporters
class application/resolvers
controller application/controllers

stdout.xml

This file is required to configure STDOUT MVC API as well as providing an integration platform of other APIs via following tags:

Logical schema:

Developers can use different bindings from those provided by framework (components in red above), provided their class extends required prototype and lies in required folder:

XML Tag Tag Attribute Class Prototype Folder
class application/renderers
controller application/controllers
handler \SessionHandlerInterface application/handlers

Following tags are not related to STDOUT MVC API but required in APIs integration via event listeners:

Event Listeners

STDOUT MVC API also allows you to manually integrate APIs or user code through event listeners in index.php file via addEventListener method. Syntax:

$object->addEventListener(EVENT_TYPE, CLASS_NAME);

Following EVENT_TYPE are available, corresponding to a prototype respective listener must extend, triggered on a lifecycle event:

Event Type Class Prototype Triggered
::START Before stdout.xml is read
::APPLICATION After stdout.xml is read, before request is read
::REQUEST After request is read, before controller runs
::RESPONSE After view resolver runs, before response is outputted
::END After response is outputted

Event listeners will be run in the order they are set once respective lifecycle event is reached. All event listeners will be located in application/listeners folder! Framework comes by default with listeners integrating APIs, adding abilities to your project (use in this order!):

Logical schema:

Developers can use different bindings from those provided by framework (right components in red above), provided their class extends required prototype and lies in required folder (click on tag to understand what it does):

XML Tag Tag Attribute Class Prototype Folder
cacheable* application/cacheables
class application/loggers
<form> @ dao application/models/dao
<form> @ throttler application/models/dao
<oauth2> @ dao application/models/dao
<by_dao> @ page_dao application/models/dao
<by_dao> @ user_dao application/models/dao

*: attribute added by Lucinda framework. To learn how to create event listeners, follow Tutorials

Attributes

As event listeners are running, they may have detected information useful for subsequent listeners and controllers. instance collects this information via setters and API makes it available throughout entire request-response phase via getters. Framework extends above with in order to collect information provided by its own event listeners, which adds following extra getters:

Method Returns Description Setter
getLogger
NULL
Gets class to log messages with
getUserId string
integer
null
Gets logged in user id
getCsrfToken string
NULL
Gets token to send as 'csrf' POST param when logging in by form
getAccessToken string
NULL
Gets token to be remembered and presented by client for stateless authentication as 'Authorization' header
getHeaders
NULL
Gets class to use in reading request headers received and writing response headers

As developers are creating their own event listeners, they will modify this class (found in application/models folder) and add setters&getters for any information they want to put in transport layer.

Helper Functions

Another side-effect of event listeners is their ability to enable quick procedural functions (all found in application/models folder) to use in models and views:

Function Arguments Returns Description Loader
SQL string $query,
array $parameters=array()

NULL
Gets class to log messages with (Tutorials)
getRemoteResource string $url,
array $fields=[]
string
integer
null
Gets logged in user id (Tutorials)
translate string $key,
string $domain="",
...$parameters
string
NULL
Gets token to send as 'csrf' POST param when logging in by form (Tutorials)

Additional APIs

In addition to APIs that are automatically integrated by framework, there are a few optional ones developers only need to bind via composer. Each adds one more ability to your project, as shown in table below:

Name Ability Added
Unit Testing API creation and execution of unit test suites (used by all APIs above) GitHub
SQL Statements API generating SQL queries programmatically based on SQL standards and vendor extensions GitHub
PHP Mailing API automating email sending based on RFC-4021 standards and signing based on RFC-6376 GitHub
RSS Feed Generator API automating and encapsulating RSS feed generation based on w3.org official standards GitHub

Technologies Used

All APIs used by framework as well as additional ones are 100% unit tested (using Unit Testing API), namespaced, PSR-4 compliant and composer autoload reliant. Their only requirement is PHP7.1+ interpreter and, generally, SimpleXML extension.

Framework Skeleton API stands alone in being functionally tested, not namespaced and loading internal dependencies (your files in application folder) using require/require_once instead. It is in developer's responsibility to implement or reorganize code there according to their project demands (Tutorials).

×