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