lucinda/php-servlets-api

Servlets API for PHP

STDOUT MVC API

Table of contents:, _(*1)

• About
• Configuration
• Binding Points
• Execution
  • Initialization
  • Binding Events
  • Configuring Shared Variables
  • Handling
• Installation
• Unit Tests
• Reference Guide
• Specifications
  • How Is Response Format Detected
  • How Are View Resolvers Located
  • How Is Route Detected
  • How Are Controllers Located
  • How Are Parameter Validators Working
  • How to Set Cookies Path and Domain
  • How Are Uploaded Files Processed
  • How Is Requested URI Processed
  • How Are Views Located

About

This API is a skeleton (requires binding by developers) created to efficiently handle web requests into server responses using a MVC version where views and models are expected to be independent while controllers mediate between the two based on user request. Designed with modularity, efficiency and simplicity at its foundation, API is both object and event oriented: similar to JavaScript, it allows developers to bind logic that will be executed when predefined events are reached while handling., _(*2)

, _(*3)

API does nothing more than standard MVC logic, so in real life it expects a web framework to be built on top to add further features (eg: DB connectivity). In order to use it, following steps are required from developers:, _(*4)

• configuration: setting up an XML file where this API is configured
• binding points: binding user-defined components defined in XML/code to API prototypes in order to gain necessary abilities
• initialization: instancing FrontController, a Runnable able to handle requests into responses later on based on above two
• binding events: setting up Runnable classes that will be instanced and run when predefined events are reached during handling process
• configuring shared variables: extend Attributes class to encapsulate variables specific to your project, to be shared between event listeners and controllers
• handling: calling run method @ FrontController to finally handle requests into responses, triggering events above (if any)

API is fully PSR-4 compliant, only requiring Abstract MVC API for basic MVC logic, PHP8.1+ interpreter and SimpleXML extension. To quickly see how it works, check:, _(*5)

• installation: describes how to install API on your computer, in light of steps above
• reference guide: describes all API classes, methods and fields relevant to developers
• unit tests: API has 100% Unit Test coverage, using UnitTest API instead of PHPUnit for greater flexibility
• example: shows a deep example of API functionality based on FrontController unit test

All classes inside belong to Lucinda\STDOUT namespace!, _(*6)

Configuration

To configure this API you must have a XML with following tags inside:, _(*7)

• application: (mandatory) configures your application on a general basis
• resolvers: (mandatory) configures formats in which your application is able to resolve responses to
• routes: (mandatory) configures routes that bind requested resources to controllers and views
• session: (optional) configures options to use automatically when creating sessions
• cookies: (optional) configures options to use automatically when setting cookies

Application

Tag documentation is completely covered by inherited Abstract MVC API specification! Since STDIN for this API is made of HTTP(s) requests, value of default_route attribute must point to index (homepage) for requests that come with no route., _(*8)

Resolvers

Tag documentation is completely covered by inherited Abstract MVC API specification!, _(*9)

Routes

Maximal syntax of this tag is:, _(*10)

<routes>
    <route id="..." controller="..." view="..." format="..." method="...">
        <parameter name="..." validator="..." mandatory="..."/>
        ...
    </route>
    ...
</routes>

Most of tag logic is already covered by Abstract MVC API specification. Following extra observations need to be made:, _(*11)

• id: (mandatory) requested requested resource url without trailing slash. Can be an exact url (eg: foo/bar) or a url pattern (eg: user/(id)). If pattern is used, each variable must be named and enclosed in parenthesis!
• controller: (optional) name of user-defined PS-4 autoload compliant class (including namespace) that will mitigate requests and responses based on models.br/Class must be a Controller instance!
• method: (optional) holds single HTTP method by which resource MUST be requested with. If request comes with a different method, a MethodNotAllowedException is thrown!

Tag example:, _(*12)

<routes>
    <route id="index" controller="Lucinda\Project\Controllers\Homepage" view="index"/>
    <route id="user/(id)" controller="Lucinda\Project\Controllers\UserInfo" view="user-info">
</routes>

^ It is mandatory to define a route for that defined by default_route attribute @ application XML tag!, _(*13)

If request came without route, default route is used. If, however, request came with a route that matches no id, a PathNotFoundException is thrown!, _(*14)

Route Parameters

Each route tag can hold one or more rules to validate values of request and path parameters that came along with request. Each parameter corresponds to a parameter tag, where validation is configurable based on attributes:, _(*15)

• name: (mandatory) name of request or path parameter you want to validate. Examples:
  • foo, if request was GET and came with query-string ?foo=bar
  • id, if route url is user/(id)
• validator: (mandatory) name of user-defined PS-4 autoload compliant class (including namespace) that will validate value of parameter.br/Must be a EventListeners\Validators\ParameterValidator instance!
• mandatory: (optional) holds whether or not parameter is mandatory (value can be 0 or 1). If none, mandatory (1) is assumed!

^ If parameter names collide, path parameters take precedence over request parameters!, _(*16)

Tag example:, _(*17)

<routes>
    <route id="index" controller="Lucinda\Project\Controllers\Homepage" view="index"/>
    <route id="user/(id)" controller="Lucinda\Project\Controllers\UserInfo" view="user-info" method="GET">
        <parameter name="id" validator="Lucinda\Project\ParameterValidators\UserNameValidator"/>
    </route>
</routes>

Session

Maximal syntax of this tag is:, _(*18)

<session save_path="..." name="..." expired_time="..." expired_on_close="..." https_only="..." headers_only="..." referrer_check="..." handler="..." auto_start="...">

Where:, _(*19)

• save_path: (optional) absolute path in which sessions are saved on server. Example: "/tmp/sessions/"
• name: (optional) name of the session which is used as cookie name (default: PHPSESSID). Example: "SESSID"
• expired_time: (optional) number of seconds after which data will be garbage collected. Example: "60"
• expired_on_close: (optional) number of seconds session cookie is expected to survive in client browser after close. Example: "120"
• https_only: (optional) marks session cookie as accessible over secure HTTPS connections. Value: "1"
• headers_only: (optional) marks session cookie as accessible only through the HTTP protocol. Value: "1"
• referrer_check: (optional) substring you want to check each HTTP Referer for in order to validate session cookie. Example: "Chrome"
• handler: (optional) name of user-defined PS-4 autoload compliant class (including namespace) that implements \SessionHandlerInterface. Example: "application/models/RedisHandler"
• auto_start: (optional) signals session to be started automatically for each request. Value: "1"

Tag example:, _(*20)

<session save_path="/tmp/sessions/" name="SESSID" expired_time="60" expired_on_close="120" https_only="1" headers_only="1" referrer_check="Chrome" handler="application/models/RedisHandler" auto_start="1">

Cookies

Maximal syntax of this tag is:, _(*21)

<cookies path="..." domain="..." https_only="..." headers_only="...">

Where:, _(*22)

• path: (optional) path on the server in which the cookie will be available on. Example: "/foo/"
• domain: (optional) the (sub)domain that the cookie is available to. Example: "www.example.com"
• https_only: (optional) signals cookie should only be transmitted over a secure HTTPS connection from the client. Value: "1"
• headers_only: (optional) signals cookie should be made accessible only through the HTTP protocol. Value: "1"

Tag example:, _(*23)

<cookies path="/" domain="example.com" https_only="1" headers_only="1">

To understand how to properly set path and domain when needed, check specification!, _(*24)

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., _(*25)

Declarative Binding

It offers developers an ability to bind declaratively to its prototype classes/interfaces via XML:, _(*26)

Programmatic Binding

It offers developers an ability to bind programmatically to its prototypes via FrontController constructor:, _(*27)

and addEventListener method (see: Binding Events section)!, _(*28)

Execution

Initialization

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

Apart of method run required by Runnable interface it implements, class comes with following public methods:, _(*30)

Where:, _(*31)

• $documentDescriptor: relative location of XML configuration file. Example: "configuration.xml"
• $attributes: see configuring shared variables.
• $type: event type (see binding events below) encapsulated by enum EventType
• $className: listener class name, including namespace and subfolder, found in folder defined when Attributes was instanced.

Example:, _(*32)

$handler = new FrontController("configuration.xml", new MyCustomAttributes("application/event_listeners");
$handler->run();

Binding Events

As mentioned above, API allows developers to bind listeners to handle lifecycle events via addEventListener method. Each EventType corresponds to an abstract Runnable class:, _(*33)

Listeners must extend matching event class and implement required run method holding the logic that will execute when event is triggered. It is required for them to be registered BEFORE run method is ran:, _(*34)

$handler = new FrontController("stdout.xml", new FrameworkAttributes("application/listeners");
$handler->addEventListener(EventType::APPLICATION, Lucinda\Project\EventListeners\Logging::class);
$handler->addEventListener(EventType::REQUEST, Lucinda\Project\EventListeners\Security::class);
$handler->run();

To understand how event listeners are located, check specifications!, _(*35)

Configuring Shared Variables

API allows event listeners to set variables that are going to be made available to subsequent event listeners and controllers. For each variable there is a:, _(*36)

• setter: to be ran once by a event listener
• getter: to be ran by subsequent event listeners and controllers

API comes with Attributes, which holds the foundation every site must extend in order to set up its own variables. Unless your site is extremely simple, it will require developers to extend this class and add further variables, for whom setters and getters must be defined!, _(*37)

Handling

Once above steps are done, developers are finally able to handle requests into responses via run method of FrontController, which:, _(*38)

• detects EventListeners\Start listeners and executes them in order they were registered
• encapsulates configuration XML file into Application object
• detects EventListeners\Application listeners and executes them in order they were registered
• encapsulates request information based on $_SERVER superglobal into Request object
• encapsulates session information based on $_SESSION superglobal as well as operations available into Session object
• encapsulates cookie operations and variables based on $_COOKIE superglobal as well as operations available into Cookie object
• detects EventListeners\Request listeners and executes them in order they were registered
• initializes empty Lucinda\MVC\Response based on information detected above from request or XML
• locates Controller based on information already detected and, if found, executes it in order to bind models to views
• locates Lucinda\MVC\ViewResolver based on information already detected and executes it in order to feed response body based on view
• detects EventListeners\Response listeners and executes them in order they were registered
• sends Lucinda\MVC\Response back to caller, containing headers and body
• detects EventListeners\End listeners and executes them in order they were registered

All components that are in developers' responsibility (Controller, Lucinda\MVC\ViewResolver, along with event listeners themselves, implement Runnable interface., _(*39)

Installation

First choose a folder, then write this command there using console:, _(*40)

composer require lucinda/mvc

Rename folder above to DESTINATION_FOLDER then create an .htaccess file there with following content:, _(*41)

RewriteEngine on
Options -Indexes
ErrorDocument 404 default
RewriteCond %{REQUEST_URI} !^/public
RewriteRule ^(.*)$ index.php

Then create a configuration.xml file holding configuration settings (see configuration above) and a index.php file (see initialization above) in project root with following code:, _(*42)

$controller = new Lucinda\STDOUT\FrontController("configuration.xml", new Attributes("application/events"));
// TODO: add event listeners here
$controller->run();

Unit Tests

For tests and examples, check following files/folders in API sources:, _(*43)

• 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:, _(*44)

• Application: reads configuration XML file and encapsulates information inside
• Request: encapsulates user request based on information in superglobals: $_SERVER, $_POST, $_GET
  • Request\Client: encapsulates client information detected from request
  • Request\Server: encapsulates server information detected from request
  • Request\URI: encapsulates uri information detected from request
  • Request\UploadedFiles\File: encapsulates information about an uploaded file
• Session: encapsulates operations to perform with a http session mapped to $_SESSION superglobal
• Cookies: encapsulates operations to perform with a http cookie mapped to $_COOKIE superglobal

Apart of classes mentioned in binding events, following abstract classes require to be extended by developers in order to gain an ability:, _(*45)

• Controller: encapsulates binding Request to Lucinda\MVC\Response based on user request and XML info
• EventListeners\Validators\ParameterValidator: performs validation of a request parameter value

Class Application

Class Application encapsulates information detected from XML and defines following public methods relevant to developers:, _(*46)

Class Request

Class Request encapsulates information detected about user request based on superglobals ($_SERVER, $_GET, $_POST, $_FILES) and defines following public methods relevant to developers:, _(*47)

Class Request Client

Class Request\Client encapsulates client information detected from request based on $_SERVER superglobal and defines following public methods relevant to developers:, _(*48)

Class Request Server

Class Request\Server encapsulates web server information detected from request based on $_SERVER superglobal and defines following public methods relevant to developers:, _(*49)

Class Request URI

Class Request\URI encapsulates path information detected from request based on $_SERVER superglobal and defines following public methods relevant to developers:, _(*50)

To understand how requested URI is processed by this class, check specifications!, _(*51)

Class Request UploadedFile

Class Request\UploadedFiles\File encapsulates information about a single file uploaded based on $_FILES superglobal and defines following public methods relevant to developers:, _(*52)

To process file uploaded, two methods were added for developers:, _(*53)

To understand how uploaded files are processed into this class, check specifications!, _(*54)

Class Session

Class Session encapsulates operations to perform with a http session via $_SESSION superglobal and defines following public methods, all relevant to developers:, _(*55)

Class Session Cookie

Class Session\Cookie encapsulates operations to perform with a http session cookie and defines following public methods, all relevant to developers:, _(*56)

Class Cookies

Class Cookies encapsulates operations to perform with a http cookie via $_COOKIE superglobal and defines following public methods, all relevant to developers:, _(*57)

Interface ParameterValidator

Interface EventListeners\Validators\ParameterValidator implements blueprint for a single request parameter value validation via method:, _(*58)

Example of a class that validates user name received as parameter (eg: /user/(name) route):, _(*59)

class UserNameValidator implements Lucinda\STDOUT\EventListeners\Validators\ParameterValidator
{
    public function validate($value)
    {
        $result = DB("SELECT id FROM users WHERE name=:name", [":name"=>$value])->toValue();
        return ($result?$result:null);
    }
}

To understand more how parameters work, check specifications and tag documentation!, _(*60)

Abstract Class EventListeners Start

Abstract class EventListeners\Start implements Runnable) and listens to events that execute BEFORE configuration XML is read., _(*61)

Developers need to implement a run method, where they are able to access following protected fields injected by API via constructor:, _(*62)

A common example of a START listener is the need to set start time, in order to benchmark duration of handling later on:, _(*63)

class StartBenchmark extends Lucinda\STDOUT\EventListeners\Start
{
    public function run(): void
    {
        // you will first need to extend Application and add: setStartTime, getStartTime
        $this->attributes->setStartTime(microtime(true));
    }
}

Abstract Class EventListeners Application

Abstract class EventListeners\Application implements Runnable) and listens to events that execute AFTER configuration XML is read., _(*64)

Developers need to implement a run method, where they are able to access following protected fields injected by API via constructor:, _(*65)

Usage example:, _(*66)

https://github.com/aherne/lucinda-framework/blob/master/src/EventListeners/SQLDataSource.php, _(*67)

Abstract Class EventListeners Request

Abstract class EventListeners\Request implements Runnable) and listens to events that execute AFTER Request, Session and Cookies objects are created., _(*68)

Developers need to implement a run method, where they are able to access following protected fields injected by API via constructor:, _(*69)

Usage example:, _(*70)

https://github.com/aherne/lucinda-framework/blob/master/src/EventListeners/Security.php, _(*71)

Abstract Class EventListeners Response

Abstract class EventListeners\Response implements Runnable) and listens to events that execute AFTER Lucinda\MVC\Response body was set but before it's committed back to caller., _(*72)

Developers need to implement a run method, where they are able to access following protected fields injected by API via constructor:, _(*73)

Usage example:, _(*74)

https://github.com/aherne/lucinda-framework/blob/master/src/EventListeners/HttpCaching.php, _(*75)

Abstract Class EventListeners End

Abstract class EventListeners\End implements Runnable) and listens to events that execute AFTER Lucinda\MVC\Response was rendered back to caller., _(*76)

Developers need to implement a run method, where they are able to access following protected fields injected by API via constructor:, _(*77)

A common example of a START listener is the need to set end time, in order to benchmark duration of handling:, _(*78)

class EndBenchmark extends Lucinda\STDOUT\EventListeners\End
{
    public function run(): void
    {
        $benchmark = new Benchmark();
        $benchmark->save($this->attributes->getStartTime(), microtime(true));
    }
}

Abstract Class Controller

Abstract class Controller implements Runnable) to set up response (views in particular) by binding information detected beforehand to models. It defines following public method relevant to developers:, _(*79)

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

Usage example:, _(*81)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/controllers/no_rest/IndexController.php, _(*82)

To understand more about how controllers are detected, check specifications!, _(*83)

Class Attributes

Class Attributes encapsulates data collected throughout request-response cycle, each corresponding to a getter and a setter, and made available to subsequent event listeners or controllers. API already comes with following:, _(*84)

Most of the data collected will need to be set by developers themselves to fit their project demands so in 99% of cases class will need to be extended for each project! Usage example:, _(*85)

https://github.com/aherne/lucinda-framework/blob/master/src/Attributes.php, _(*86)

Specifications

Since this API works on top of Abstract MVC API specifications it follows their requirements and adds extra ones as well:, _(*87)

• How Is Response Format Detected
• How Are View Resolvers Located
• How Is Route Detected
• How Are Controllers Located
• How Are Parameter Validators Working
• How to Set Cookies Path and Domain
• How Are Uploaded Files Processed
• How Is Requested URI Processed
• How Are Views Located

How Is Response Format Detected

This section follows parent API specifications only that routes are detected based on value of $_SERVER["REQUEST_URI"]., _(*88)

How Are View Resolvers Located

This section follows parent API specifications in its entirety., _(*89)

How Is Route Detected

This section follows parent API specifications only that routes are detected based on value of $_SERVER["REQUEST_URI"]. Let's take this XML for example:, _(*90)

<application default_route="index" ...>
    ...
</application>
<routes>
    <route id="index" .../>
    <route id="users" .../>
    <route id="user/(id)" .../>
</routes>

There will be following situations for above:, _(*91)

How Are Controllers Located

This section follows parent API specifications only that class defined as controller attribute in route tag must extend Controller., _(*92)

How Are Parameter Validators Working

To better understand how validators attribute in application XML tag plays together with parameter sub-tags in routes tag in order to locate validators to run based on incoming request, let's take this XML for example:, _(*93)

<routes>
    <route id="users/(uname)" method="GET" ...>
        <parameter name="uname" class="Lucinda\Project\ParameterValidators\UserName"/>
    </route>
    <route id="user/info" method="POST" ...>
        <parameter name="id" class="Lucinda\Project\ParameterValidators\UserId"/>
        <parameter name="name" class="Lucinda\Project\ParameterValidators\UserName" mandatory="0"/>
    </route>
    ...
</routes>

When a request to /users/aherne is received, API will:, _(*94)

• detect route with id users/(uname) and request parameters received (path parameters, GET, POST)
• check if route is called with GET method. If not, a MethodNotAllowedException is thrown!
• instances Lucinda\Project\ParameterValidators\UserName and runs validate method on value of "uname" path parameter. If param not sent or validation fails, a ValidationFailedException is thrown!

When a request to /users/info is received, API will:, _(*95)

• detect route with id user/info and request parameters received (path parameters, GET, POST)
• check if route is called with POST method. If not, a MethodNotAllowedException is thrown!
• instances Lucinda\Project\ParameterValidators\UserId and runs validate on value of "id" request parameter. If param not sent or validation fails, a ValidationFailedException will be thrown!
• instances Lucinda\Project\ParameterValidators\UserName and runs validate on value of "name" request parameter. If param sent and validation fails, a ValidationFailedException will be thrown!

All parameter validators need to be PSR-4 autoload compliant and implement EventListeners\Validators\ParameterValidator!, _(*96)

How to Set Cookies Path and Domain

Table below shows the effects of path attribute @ cookies XML tag:, _(*97)

Table below shows the effects of domain attribute @ cookies XML tag:, _(*98)

How Are Uploaded Files Processed

Unlike $_FILES superglobal, like parameters sent by $_GET or $_POST, API preserves structure sent in form, so:, _(*99)

<input type="file" name="asd[fgh]"/>

Once posted, uploadedFiles method will return:, _(*100)

[
  "asd"=>["fgh"=>object]
]

Where object is a Request\UploadedFiles\File. To retrieve uploaded files, use uploadedFiles method @ Request!, _(*101)

How Is Requested URI Processed

API breaks down requested URI (value of REQUEST_URI param @ $_SERVER) into relevant components based on following algorithm:, _(*102)

• it first detects context path by stripping SCRIPT_FILENAME from DOCUMENT_ROOT. Normally, context path is empty since sites are deployed to a specific hostname, but there are cases in which they are deployed on localhost directly, so when REQUEST_URI is http://localhost/mySite/foo/bar, context path will be mySite
• it strips context path and QUERY_STRING from REQUEST_URI in order to detect requested page. If no specific page was requested as in http://www.example.com, homepage is assumed, so requested page will be an empty string
• it records query string and its array representation based on QUERY_STRING param @ $_SERVER. Recording an array representation of query string parameters separate from that returned by parameters method of Request is justified when a non-GET request is received.

Examples:, _(*103)

How Are Views Located

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