Taeluf.com

Liaison Web Server

A Liaison web server is typically starts with a Liaison App for the website's theme, public files, configs, core features, and views. Then third-party apps and additional apps of your own can be added to create well-organized website features.

Also See:

  • Libraries Documentation - How to build apps: Details on routing, views, hooks, and more.
  • Integration - Integrate a Liaison app into another webserver (such as wordpress, laravel, or a diy setup)
  • README

Through these examples, we'll build a fully functional Liaison website.

Sections of this document

  • Directory Structure
  • deliver.php
  • Site app
    • Theme
    • Configuration site/config.json
  • Environment settings
  • Static Files
  • File Uploads
  • Debugging
  • Database Setup (PDO)

Web Server Directory Structure

This is a sample structure, and you're welcome to use your own.

DOCUMENT_ROOT
    - .env/ <- Your environment configs
    - .htaccess <- Used by apache to route to your deliver.php
    - composer.json 
    - deliver.php <- Every request is routed through this file
    - site/ <- Your primary Liaison app, with your theme & core pages & features.
        - config.json 
        - public/index.php <- your home page
    - apps/ <- Additional apps you develop, to organize different features of your website
    - deliver/ <- Optional directory to organize different aspects of your setup

deliver.php

This script sets up your webserver & delivers a response.

Notes:

  • Apps are setup by the Package class. (eventually, we'll add an App class)
  • Most features are created through Addons.
  • Lia\Package\Server extends Lia\Package and initializes routes, views, cache, and more, by calling addons within the built-in app.
<?php

require_once(__DIR__.'/vendor/autoload.php');

$lia = new \Lia();

// Add the built-in App, which provides all the web-server features.
$server_app = new \Lia\Package\Server($lia, $fqn='lia:server');  // dir & base_url not required

// Add your app, providing home page & other core pages & features
$site_app = new \Lia\Package\Server($lia, 'myname:site', $app_dir = __DIR__.'/site/', ?$base_url = '/');

// delivers files in `site/public/*` 
$lia->deliver();

Site app

Typically, the Site app is your core application which provides a theme, webserver configuration, public routes, a cache dir, and hooks.

Most features are covered in Libraries Documentation, so we limit this section to webserver-related needs.

Theme

A theme is the site's base layout and styles. Multiple themes can be setup, then switched out at runtime.

A basic theme:

<?php
    // $header = $lia->view('theme/header'); Optional way to better sort your code.
    // $footer = $lia->view('theme/footer);
?>
<!DOCTYPE html>
<html>
    <head>
		<meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta charset="utf-8"  />
        <meta http-equiv='content-language' content='en' />
        <?=$lia->getHeadHtml();?>
    </head>
    <body>
        <header>
            <?php // echo $header; # We'll use this later ?>
        </header>
        <main>
            <div class="content">
                <?=$content?>
            </div>
        </main>
        <footer>
            <?php // echo $footer; # We'll use this later ?>
        </footer>
    </body>
</html>

Notes:

  • getHeadHtml() will print a link to your (compiled) stylesheets & scripts, plus SEO information you've added.
  • the view() calls for header/footer MUST come before getHeadHtml(), so the stylesheets & scripts will be included in the <head>
  • Var $content is passed to your theme. This comes from your route, and could have been modified by hooks.

Configuration - site/config.json

TODO - I swear you need configs, but I can't figure out what they are!

Some apps will require configs, and those should go in site/config.json, typically.

Environment Settings

Liaison does not have native support for environment settings, but these are useful for database setup, at the very least.

Options:

Static Files

Static files can be delivered simply by checking if __DIR__.$url is a file & delivering it, then exiting. For more information, see @see(docs/api/code/class/Router/FastFileRouter.php.md, Lia\FastFileRouter).

<?php
/** `require` a php file based on the url. Url `/some_file` will deliver `api/some_file.php`. `..` is removed to prevent path traversal.
* 
* @param $dir the directory the files are in
* @param $args array to `extract()` and make values available to your PHP sript.
*/
\Lia\FastFileRouter::php($dir = __DIR__.'/api/',$args = []);


// Send a static file for the url. `/some_file.jpeg` will deliver `file/some_file.jpeg`. 
// `..` is removed to prevent path traversal.
// `.php` files are not delivered.
\Lia\FastFileRouter::file(__DIR__.'/file/');

File Uploads

TODO - not natively supported ....

Use something else for file uploads, store them in a directory, and use the static files instructions above to deliver them, if that's the intent.

Debugging

Liaison has a dump debugger that doesn't expand objects, thus preventing memory crashes. It will also print all of its addons, routes, methods, properties, packages (apps), and prefixes.

<?php
// Print details about your liaison instance
$lia->dump();
// print details about any value
$lia->dump($var);
// print the properties of an opject
$lia->dump(get_object_vars($object));

Database Setup (PDO)

There is no native database support, but this covers a typical setup using shared properties (Lia::get() & Lia::set()). You can use any database layer you like, but I recommend taeluf/big-db, if not using raw \PDO.

Update .env/secret.json with your database settings: (add .env/ to your .gitignore)

{
    "mysql.host": "localhost",
    "mysql.dbname": "my_database",
    "mysql.user": "user_name",
    "mysql.password": "Super Secure Password"
}

Update deliver.php with a PDO instance:

<?php # require vendor

$lia = new \Lia();

// load environment settings & initialize PDO
$env = json_decode(file_get_contents(__DIR__.'/.env/secret.json'), true);
$pdo = new \PDO('mysql:dbname='.$settings['mysql.dbname'].';host='.$settings['mysql.host'],
            $settings['mysql.user'],$settings['mysql.password']);

// set on liaison
$lia->set('pdo', $pdo);
// $pdo = $lia->get('pdo'); # any code that has access to `$lia` can get the pdo instance.

# add apps and deliver()

Databse layers to consider

I love my big-db library, and really enjoyed Redbean when I used it in the past. I haven't tried nette, medoo, or cake. There are many other options too. Also, PDO on its own is pretty great.