Download the PHP package lucinda/abstract_mvc without Composer

Abstract MVC API

Table of contents:

• About
• Configuration
• Binding Points
• 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 Views Located

About

This API is a skeleton (requires binding by developers) created to contain parts of a MVC API that do not relate to STDIN type (console, url request or exception to be handled). It serves as a foundation for:

• STDOUT MVC API: where STDIN comes from URL requests
• STDERR MVC API: where STDIN comes from STDERR of url/console requests
• Console MVC API (to be done): where STDIN comes from console requests

API is fully PSR-4 compliant, only requiring PHP8.1+ interpreter and SimpleXML extension. To quickly see how it works, check:

• 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
• reference guide: describes all API classes, methods and fields relevant to developers
• UnitTest API instead of PHPUnit for greater flexibility

• routes: (mandatory) holds routing rules for handled requests
  • route: (optional) holds routing rules specific to a requested URI based on attributes:
    • id: (mandatory) unique route identifier (eg: requested requested resource url without trailing slash)
      Example: "users/(name)"
    • controller: (optional) name of user-defined PS-4 autoload compliant class (including namespace) that will mitigate requests and responses based on models.
      Must be a Runnable instance!
    • view: (optional) holds user-defined template file that holds the recipe of response for request. Example: "homepage"
    • format: (optional) holds response format, if different from default_format @ resolvers!

Tag example:

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 via XML:

Programmatic Binding

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

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
  • route XML tag matching id of request handled
  • resolver XML tag matching response format for request handled
• Response: encapsulates response to send back to caller
  • Response\Status: encapsulates response HTTP status
  • Response\View: encapsulates view template and data that will be bound into a response body

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

• Runnable: defines blueprint for a component whose logic can be run
• Response body

Class Application

Class Application encapsulates information detected from XML and defines following public methods relevant to developers:

Other public methods are relevant only to APIs built on top of this.

Class Application Route

Class Application\Route encapsulates information detected from matching route XML tag and defines following public methods:

Class Application Format

Class Application\Format encapsulates information detected from matching resolver XML tag and defines following public methods:

To better understand how views will be resolved in the end, check How Are Views Resolved documentation below!

Class Response

Class Response encapsulates operations to be used in generating response. It defines following public methods relevant to developers:

When API completes handling, it will call commit method to send headers and response body back to caller!

Class Response Status

Class Response\Status encapsulates response HTTP status and defines following public methods relevant to developers:

Class Response View

Class Response\View implements \ArrayAccess and encapsulates template and data that will later be bound to a response body. It defines following public methods relevant to developers:

By virtue of implementing \ArrayAccess, developers are able to work with this object as if it were an array:

Class Response Redirect

Class Response\Redirect is a Runnable that encapsulates http status 301/302 redirection with its options. It defines following public methods relevant to developers:

Example:

Interface Runnable

Interface Runnable interface it implements, class comes with following public method:

Usage example:

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

Abstract Class ViewResolver

Abstract class ViewResolver implements Runnable and encapsulates conversion of Response\View to response body for final response format.

Developers need to implement run method for each resolver, 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/ViewResolvers/Html.php

In order to better understand how view resolvers work, check How Are View Resolvers Located section below!

Specifications

Since this API is a skeleton to build MVC APIs on top it comes with a series of specifications that may or may not be automatically implemented here:

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

How Is Response Format Detected

To better understand how default_format and default_route attributes in resolvers tag, let's take this XML for example:

There will be following situations for above:

This logic requires to be implemented by child APIs because the nature of resolvers differs based on STDIN type!

How Are Views Resolvers Located

To better understand how default_format attribute in resolvers tag, let's take this XML for example:

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

• file autoloaded will be src/ViewResolvers/Html.php
• class found there must:
  • be named: "Html"
  • belong to namespace: "Lucinda\Project\ViewResolvers"
  • extend ViewResolver

This logic is entirely implemented by this API! Developers only need to plug in suitable ViewResolver classes in XML.

How Is Route Detected

To better understand how default_route attribute in routes tag, let's take this XML for example:

Assuming STDIN comes from HTTP requests, there will be following situations for above:

This logic requires to be implemented by child APIs since logic of request depends on STDIN type!

How Are Controllers Located

To better understand how default_route attribute in routes tag, let's take this XML for example:

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

• file autoloaded will be: "src/Controllers/Homepage.php"
• class found there must:
  • be named: "Homepage"
  • belong to namespace: "Lucinda\Project\Controllers"
  • extend Lucinda**???**\Controller

As you can see above, controller namespace was ommitted because controller itself must be implemented by child APIs (since it depends on STDIN type).

How Are Views Located

To better understand how views attribute in routes tag, let's take this XML for example:

In that case if route "user/info" matches STDIN request then:

• file autoloaded will be: "application/views/user-info.???"

As you can see above, view extension was ommitted because view itself must be implemented by child APIs (since it depends on STDIN type).