@fishawack/watertight v5.0.1

Watertight Readme

A lightweight PHP login wrapper to server a HTML site/app

• Updated 7 December 2016 : Query string variables and page return after login
• Updated 21 October 2016 : Generate routes
• Updated 14 June 2016
• Created: 26 May 2016

Watertight uses Plankton for a lightweight MVC

Dependancies, installed via Composer

• Formidable
• Session

In simple profile testing it adds between 493-832 KB per page load.

Install

Use composer for PHP dependancies. Instructions on installing composer.

If composer in path.

Go to: www/watertight

$ composer install

Instructions

Secured app

To secure a HTML site, place all HTML files in to:

/watertight/app/views/securedsite/

And all public viewable files in (eg. CSS, JS, images):

/watertight/public_html/

Edit controller:

/watertight/app/controllers/securedsite.php

Edit each route and view template, eg:

If navigating to URL /terms the below will display terms.html

'/terms' => function($app) {
    $app['model']->requireLogin();

    return $app['model']->getStaticViewFile('terms');
}

The secured site requires at least one route, defined in default - the home page.

Required route:

• /

Required view:

• app/views/securedsite/index.html

Watertight uses routes, so certain slugs are reserved and can not be used in the secured app.

Reserved routes, do not use:

• admin
• error
• login
• logout

Watertight config

All config options are optional, but some should be tweaked :D

Edit:

/watertight/app/app.php

'config' => array(
  'debug'       => false,
  'urlrewrite'  => true,
  'siteurl'     => '',
  'database'    => false,
)

debug

Dugh. Outputs all PHP errors to the screen. Not a good idea on Production sites.

urlrewrite

Likely to be running through Apache. Requires modrewrite to strip front controller and URL segments to work.

If it's not possible to remove front controller, change to false, but remember to include index.php in all links.

siteurl

Better to have full URLs for links, add domain for Watertight to include full links. Doesn't effect secured app. Eg. http://watertight.local

*No need for end slash

database

Watertight stores all user/pass details in /watertight/app/users.php. Simple for a low number of users. It's possible to use MySQL as the data source. Database TBC.

User accounts

Edit:

/watertight/app/users.php

The file is annotated. One thing to note, there are 2 account types:

• admin
• reader

Go to /admin to view a list of user accounts.

Auto / pre-filled login

Forgetting the stupidity of having a password protected site that 'auto' logs-in. Password details can be passed via query string variables in the format:

/login?uName=client&pwd=password

E.g.

ione.fishawackmeetings.com/login?uName=client&pwd=password

The username/password can also be apended to pages inside Waetrtight, and they will be preserved through the login process.

E.g.

ione.fishawackmeetings.com/path/to/innerpage.html?uName=client&pwd=password

Secured App Variables

In addition to uName and pwd, Watertight can pass other query string variables through to the protected app. Variables should be defined in qsVariables (app.php > config), stamp is defined by default for use in Wave webcast.

'qsVariables' => array('stamp')

Test cases

http://watertight.local/?stamp=500 // stamp on index page
http://watertight.local/?uName=client2&pwd=password // u/p on index page
http://watertight.local/login?stamp=500 // stamp on login page, will pass to index after
http://watertight.local/login?uName=client2&pwd=password // u/p on login page
http://watertight.local/page-1?stamp=500 // stamp on page-1 page, will redirect to login, then redirect to page-1 on successful login and preserve stamp
http://watertight.local/page-1?uName=client2&pwd=password&stamp=500 // u/p and stamp on page-1 page, will redirect to login pre-fill u/p, on successful login will redirect to page-1 and preserve stamp

Watertight in a sub-folder

Expected use is to have the app above webroot, all publically accessible files should be in public_html which is assigned as webroot in the webserver config.

├── app
│   ├── CustomEnglish.php
│   ├── Model.php
│   ├── app.php
│   ├── autoload.php
│   ├── controllers/
│   ├── users.php
│   └── views/
├── composer.json
├── composer.lock
├── logs/
├── public_html
│   ├── .htaccess
│   ├── bootstrap/
│   ├── css/
│   └── index.php
└── vendor

It's possible to have the app at root for use in subfolders but is less secure. Measures are in place to prevent direct access to app folders in .htaccess for Apache.

Reserved paths:

• /app
• /logs
• /vendor

Move all files in public_html to the same level as the files above. Delete public_html.

In index.php change line 6 to:

$appPath = '';

Make sure siteurl is set to absolute path including subfolder in app.php.

└── subfolder
    ├── .htaccess
    ├── app/
    ├── bootstrap/
    ├── composer.json
    ├── composer.lock
    ├── css/
    ├── index.php
    ├── logs/
    └── vendor/

At this point any of the secured app public files and folders should also be at this level, eg. js/, media/

'Pages' still go in app/views/.

Several instances of Watertight on the same domain (inc subfolders)

Logging in once will login to all instances of Watertight on the same domain - might be desired.

To keep each instance unique, the session segment should be unique.

In index.php on line 20 set the session to a unique name, eg.

$sessionSegment = $session->getSegment('asco2016');

.ENV file

Usually the .env file lives in the root of the project and you have the public_html served one under, we've have to move this file elsewhere due to the nature of watertight.

It now lives under securedsite folder in views