npm package: @fishawack/watertight
Description: Bridge between watertight php and node
Author: Mike Mellor
Latest version: 5.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](https://github.com/Gregwar/Plankton) for a lightweight MVC

Dependancies, installed via Composer

 + [Formidable](https://github.com/Gregwar/Formidable)
 + [Session](https://packagist.org/packages/aura/session)

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

### Install

Use composer for PHP dependancies. [Instructions on installing composer.](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)

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