katmore/flat

experimental framework for php

The Flat Framework

An experimental framework for php, _(*1)

It was created to allow a project to be organized in a hierarchical manner similar to a REST service., _(*2)

Architecturally, it facilitates a broad swathe of design patterns using a client-server process flow., _(*3)

Features

• HTML templating: convenience classes facilitating sophisticated templating
• Front-End Routing: flexible dynamic routing for the HTML views
• Back-End Webservice: convienence classes to faciliate actual RESTful APIs
• Command line scripts: convenience classes to faciliate creation of recurring (cron), deamons, and ad-hoc scripts

Installation

The Flat Framework can be the basis of a new project or added to an existing project, _(*4)

New Projects

The easiest way to get going with The Flat Framework is to copy the flat boilerplate webapp., _(*5)

Step 1. Composer 'create-project' (flat boilerplate webapp)..., _(*6)

composer create-project katmore/flat-webapp my_project_dir

(copies this repo and configures php dependencies), _(*7)

Step 2. Bower update, _(*8)

cd my_project_dir
bower update

(installs static dependencies), _(*9)

Existing Projects

Step 1. Using composer, _(*10)

cd my_project_dir
composer require katmore/flat

Step 2. Bower update, _(*11)

cd my_project_dir
bower update

Architecture

The components of flat architecture facilitate a client-server process flow..., _(*12)

• resources: An abstract hierarchical tree of the applications components.
• app objects: A group of instantiable php objects.
• app routes: A group of of routes that an application controller can access to resolve a client request.
• app controllers: A group of application "entry-points"; i.e. the "server" which processes a request from the "client".
• requests: A request consists of a client inquiry which provides a resource and any associated input data to an app controller.
• route maps: A route map consists of multiple routes that each must be resolved by an app controller
• resolvers: A resolver instantiates app objects when given a resource.

Admittedly, the component organization of the flat architecture is rigidly attached to the client-server model. Despite this, the programming design constraints of a flat based project are actually very minimal. For this reason, flat can be argued to be a lightweight framework. Any programming design pattern can be used within a flat project., _(*13)

However... there is an idealized programming design use case neatly bundled within the architecture., _(*14)

Groan...yes, it is yet another design pattern., _(*15)

The Resource-Route-Controller is a novel design pattern invented in tandem with flat. It is, though, intended to be a very lightweight design pattern that should not keep other design patterns (MVC, MVP, MVVM) from being incorporated. It is described further in a section below., _(*16)

The hierarchical organization of a flat project is abstracted into multiple abstract levels of programming design (not just the path names of scripts and dependency file structure)., _(*17)

The following sections contain further details regarding concepts and terminology encountered in flat., _(*18)

Resource:

A "resource" is a string value comprised of one or more "segments", each "segment" being delineated by either a backslash "\" or forward-slash "/"., _(*19)

For example, given the following URL:, _(*20)

https:/example.com/my_app/my_app_frontend/my_frontend_view

An app controller might extract the URL path as the resource /my_app/my_app_frontend/my_frontend_view and then check if a php class exists with the name \my_app\my_app_frontend\my_frontend_view, and instantiate the class, which becomes an app object..., _(*21)

$check_class = $_SERVER ['PATH_INFO'];
$check_class = str_replace('/','\\',$check_class);
if (class_exists($check_class)) {
   new $check_class;
}

Note: flat has convenience classes that facilitate more complex routing than the trivial example above. These facilitate more complex aspects, such as dealing with associated request input data., _(*22)

See * Route Rules definition below * Route Factory definition below * Resolver Class https://github.com/katmore/flat/blob/master/src/flat/core/resolver.php, _(*23)

Route Factory:

A "route factory" facilitates creating a "route map" for resolving a "resource"., _(*24)

Route Map:

A "route map" consists of "route rules" which determine how a "resource" corresponds to php classnames within a php sub-namespace., _(*25)

Entry Point Controller:

An entry-point controller script uses a "resolver" to instantiate "app objects". based on the "route map" logic created in this, _(*26)

An example of an entry-point script can be seen in the 'flat-webapp' github repo: https://github.com/katmore/flat-webapp/blob/master/web/api.php, _(*27)

The "Resource-Route-Controller" Design Pattern

• resource
  • input data associated
• controller
  • request Determines the resource (and any input) to provide the controller

"Resource-Route-Controller"

Ideal process flow incorporating Resource-Route-Controller design using 'client-server' model 1. An application controller is provided a "resource" along with any "input" 2. A controller "resolves" the "resource" into one or more objects which contain the application logic., _(*28)

Legal

Copyright (c) 2012-2019 Doug Bird - retran@gmail.com. All Rights Reserved., _(*29)

This software is distributed under the terms of the MIT license or the GNU General Public License v3.0., _(*30)