Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/katmore/flat

an experimental framework for php
https://github.com/katmore/flat

flat-framework http-router http-routing php-framework php-library php7 rest-api restful restful-api restful-webservices template-engine templating vanilla-php webservice

Last synced: about 12 hours ago
JSON representation

an experimental framework for php

Awesome Lists containing this project

README 

        
# The Flat Framework



**An experimental framework for php**



It was created to allow a project to be organized in a hierarchical manner similar to a REST service.



Architecturally, it facilitates a broad swathe of design patterns using a client-server process flow.



## 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**



### New Projects

The easiest way to get going with **The Flat Framework** is to copy the [flat boilerplate webapp](https://github.com/katmore/flat-webapp).



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



```bash

composer create-project katmore/flat-webapp my_project_dir

```

*(copies this repo and configures php dependencies)*



**Step 2. Bower update**

```bash

cd my_project_dir

bower update

```

*(installs static dependencies)*



### Existing Projects

**Step 1. Using composer**

```bash

cd my_project_dir

composer require katmore/flat

```



**Step 2. Bower update**

```bash

cd my_project_dir

bower update

```



## Architecture

The components of *flat* architecture facilitate a *client-server* process flow...



  * **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.



However... there is an idealized programming design use case neatly bundled within the architecture.



Groan...yes, it is yet another design pattern.



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.



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).



The following sections contain further details regarding concepts and terminology encountered in *flat*.



### Resource:

   A "resource" is a string value comprised of one or more "segments", 

   each "segment" being delineated by either a backslash "\" or forward-slash "/".

   

   For example, given the following URL:

   

```

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*...

   

```php

$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.

   

   *See*

    * **Route Rules** definition below

    * **Route Factory** definition below

    * **Resolver Class** https://github.com/katmore/flat/blob/master/src/flat/core/resolver.php



### Route Factory:

   A "route factory" facilitates creating a "route map" for resolving a "resource".



### Route Map:

   A "route map" consists of "route rules" which determine how a "resource" 

   corresponds to php classnames within a php sub-namespace.

   

### Entry Point Controller:

   An entry-point controller script uses a "resolver" to instantiate "app objects". based

   on the "route map" logic created in this  

   

   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



## 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.



## Legal

Copyright (c) 2012-2019 Doug Bird - . All Rights Reserved.



This software is distributed under the terms of the [MIT license](LICENSE) or the [GNU General Public License v3.0](GPLv3).