Front Controller

Online demo (username : p ; password : (leave empty))

Download version 0.25 (uses XML instead of JSON)

Version 0.15 (uses a cookie instead of $_SESSION)

Version 0.12 (uses sessions ; bilingual : french and english)

Version 0.6 (english only)

What is Front Controller ?

Front Controller (FC) is a collection of PHP scripts meant to create portals.

It allows you to create many pages, protected by login and with database access.

It is 545 lines of PHP, HTML and CSS code across 15 files.

It has no JavaScript code.

Structure

The application starts with app.php (the single controller).

app.php first registers an autoload (so no need for includes anywhere)
it then parses the URL for the page name and language
the view is loaded
by default, the view then verifies if the user is logged in (and shows a login page if not)

To find a view, app.php loads the view class by prepending 'Vue' to it.

So URL /app.php/En/Bonjour/ loads class VueBonjour from the app/vue/VueBonjour.php file.

Features

Supports multiple languages (and can easily support more).

All URLs are created at a central place. (See URL::FullURL() below). The current language is added to all URLs.

Does not use sessions : There is no "logout delay".

Uses only one cookie : Allows to be connected as long as the browser remembers the cookie.

That cookie is saved in the database and will only change at user request (For example, if the user wishes to log out on other devices).

When the user logs out, the URL is unchanged (so when logging back in, the user will be where he was before logging out).

In fact, the login page does not have its own URL. Instead, a 401 error containing the login page is returned if logging in is required by the view.

Resubmission : If the user was filling a form and was logged out when submitting it, the login page allows him to resend the form data while logging back in.

It is possible to decide which views need login and which don't. (See authenticate() below).

Installation

FC requires a MySQL database to save users.

First create the database and the user PHP will access it with :
Copy the app/ and style/ folders and the app.php file to where you want the application to be installed.
You may rename the app.php script to something else ('index.php' for example).
Do not forget to block access to the app/ folder by either moving it outside of the document root (and modifying app.php to point to its new location) or by adding this to an app/.htaccess file :
```
Require all denied
```
or this to your <VirtualHost> block :
```
<DirectoryMatch "/app/">
	Require all denied
</DirectoryMatch>
```
To customize the connection to the database, edit the app/model/Mdl.php script.
You may now login as user 'admin' with an empty password (do not forget to change it).

Examples

Look at the VueUsers.php view and the MdlUser.php model for an example.

Creating a new page

Creating a new page is simple.

First create a class named VueBonjour and save it in app/vue/VueBonjour.php

<?php
	class VueBonjour extends Vue {
		protected function render() {
			$this->renderTitle('Bonjour');
?>
<p>Bienvenue.
<?php
		}
	}
?>

It will then be accessible at the /app.php/En/Bonjour/ URL.

Every view inherits from the abstract Vue class.

By default, every class must implement the abstract 'render()' method.

It is called whenever the vue must be rendered.

Vue.php also provides a renderTitle($title) function to render the page title and optionally the navigation menu at the top.

Adding it to the navigation menu

To add the page to the navigation menu, edit the $pages array in the app/vue/Vue.php file.

Extra methods

Look inside Vue.php for method signatures. (all the following functions are protected)

You may implement these methods in your views.

authenticate()
Allows a page to require login.
Return true to allow and false to require a login.
Defaults to AUTH::IsLoggedIn();
authorize($post)
Allows or denies access to a page.
Return true to allow and false to deny.
$post tells you if the request was a POST request.
Defaults to true
handleGET()
Allows you to do extra processing on GET requests (before render()).
handlePOST()
Allows you to do extra processing on POST requests (before render()).
This is where you can handle form submissions.
When you are done, call HTTP::Reload() to reload the page.
(If you do not call HTTP::Reload(), the user will be prompted to resumbit when the reload button is clicked)

Creating a new model

When creating a new view, you may want to access the database.

Do so using a model.

In the app/model/ folder, model classes inherit from the abstract Mdl class.

Example model :

<?php
	class MdlBonjour extends Mdl {
		function getAllBonjours($id = 0) {
			$sth = $this->pdo()->prepare('SELECT name FROM bonjour WHERE id = :id');
			$sth->execute(array('id' => $id));
			return $sth->fetchAll();
		}
	}
?>

Mdl.php provides a pdo() method which gives you access to the PDO object.

It is recommended to create one model per database table.

Global constants

LANG: The language code from the URL.
PAGE: The name of the page from the URL.
SUBPAGE: The name of the subpage from the URL.
SUBSUBPAGE: The name of the subsubpage from the URL.

Customization

Changing the default language :
Edit the app.php file :
```
define('LANG', $lang ?: 'En');
```
Changing the default page :
Edit the app.php file :
```
define('PAGE', $page ?: 'Home');
```

Changing the database access information :

Edit the app/model/Mdl.php file :

$pdo = new PDO('mysql:dbname=fc;host=localhost;charset=utf8mb4', 'fc', '1qaz2wsx');

Navigation menu pages :

Edit the app/vue/Vue.php file :

private $pages = array(
	array('PageOne', 'Title of page one'),
	array('PageTwo', 'Title of page two'),
	array(array('Bonjour', 'SubPage'), 'Title of SubPage of Bonjour')
);

Utilities

AUTH::GetUser()

Gets the logged in user.

Returns keys id, name, fullname.

AUTH::IsLoggedIn()

Tells if the user is logged in.

AUTH::IsAdmin()

Tells if the user is an admin.

URL::FullURL()

Returns a root relative URL.

URL::FullURL('Bonjour', 123, array('s' => 456))
returns /app.php/En/Bonjour/123/?s=456

URL::FullURLHTML()

Same as URL::FullURL() but for an HTML context :

<a href="<?= URL::FullURLHTML('Bonjour') ?>">Bonjour</a>

URL::DomainURL()

Returns a full URL (with host name).

URL::DomainURL('Bonjour')
returns http://fc.philippe97.ca/app.php/En/Bonjour/

URL::DomainURLHTML()

Same as URL::DomainURL() but for an HTML context.

URL::Relative($base, $url)

Resolves a relative URL to a base URL.

$base is the full base URL (http://...).

$url is the relative URL (http://... or //... or /... or ...).

URL::RelativeHTML($base, $url)

Same as URL::Relative() but for an HTML context.

URL::AppURL()

Returns a URL relative to the folder containing app.php.

URL::AppURL('Bonjour')
returns /Bonjour if the app.php script is at the root.

URL::AppURLHTML()

Same as URL::AppURL() but for an HTML context :

<link href="<?= URL::AppURLHTML('style', 'sheet.css') ?>" rel=stylesheet />

HTTP::Reload()

Reloads the current URL.

Useful in handlePOST() to change the POST request into a GET.

(if not called, the user will be prompted to resubmit if the reload button is clicked)

HTTP::ReloadURL()

Redirects to another URL.

Accepts the same arguments as URL::FullURL()

Example : HTTP::ReloadURL('Bonjour', 456)

HTTP::Resubmit()

Resubmits the current URL (with 307 code).

Tells the browser to resend the POST request.

HTTP::ResubmitURL()

Resubmits to another URL.

Accepts the same arguments as URL::FullURL()

Example : HTTP::ResubmitURL('Bonjour', 456)

STR::text($key)

Returns a translated string.

Example : STR::text('Welcome')

STR::html($key)

Same as STR::text($key) but for an HTML context.

Example : <span><?= STR::html('Welcome') ?><span>

Tips and tricks

Adding a language

Edit the app/xml/Traduction.xml file and add a new element.

<Es>
	...
</Es>

You may copy the element of another language.

Sub-pages (i.e. `/app.php/En/Bonjour/SubPage/`)

There are many ways to implement sub-pages in FC.

One of them is to create a view for the parent page which includes the child pages.

To simplify things, you may want to give SUBPAGE a default value of 'Index' in app.php :

define('SUBPAGE', $subpage ?: 'Index');

The view (app/vue/VueBonjour.php) may then load a separate PHP file for every sub page :

<?php
	class VueBonjour extends Vue {
		protected function render() {
			$file = __DIR__ . '/Bonjour/' . SUBPAGE . '.php';
			if (file_exists($file))
				include $file;
			else
				(new Vue404())->handle();
		}
	}
?>

Every PHP file in the Bonjour/ folder may start like this (app/vue/Bonjour/Index.php in this case) :

<?php $this->renderTitle('Index'); ?>
<p>This is the Index page.</p>
<ul>
	<p><li><a href="<?= URL::FullURLHTML(PAGE, 'AAA') ?>">AAA</a></li>
</ul>

app/vue/Bonjour/AAA.php may contain :

<?php $this->renderTitle('AAA'); ?>
<p>This is the AAA page.</p>

Public pages

Sometimes, you may want to make a page accessible to all without having to log in.

To do that, add this to your view class :

protected function authenticate() {
	return true;
}

Removing `app.php` from the URL

To remove app.php from the URL, add one of these two lines to your <VirtualHost> block :

RewriteEngine On

# At the root folder :
RewriteRule ^/((En|Fr)(/.*)?)?$ /app.php/$1

# In a subfolder :
RewriteRule ^/(subfolder)/((En|Fr)(/.*)?)?$ /$1/app.php/$2

Or this to your .htaccess file :

RewriteEngine On
RewriteRule ^((En|Fr)(/.*)?)?$ /app.php/$1

You may add more languages in the rule.