Liaison

A PHP Framework and a set of components for developing webapps and websites

Next Version (release TBD)

This version is planned for the future & as of Apr 12, 2022 development has not begun. Just notes. See Status.md

v0.6 will be the next version & will come with major internal changes but likely will not have any significant changes to the API. The current version has Package & Addon as sub-classes of Lia. Also, there are MANY properties by-reference. These complexities are slow & confusing. In the new version, Packages & Addons will likely not extend from Liaison any further. And by-reference properties will be removed.

Beta Version (April 5, 2021)

v0.5 marks the official beta. Software-wise, it's basically ready to go. Documentation wise, it's pretty poor. There are some weird things in here that will make it hard for you to use to it's full ability until I finish writing proper documentation. There's also some minor code issues in Liaison that I do need to fix.

My advice: Admire what it could be, keep an eye on it, and use it when it is a little more mature.

Quick Start

Write a deliver script, such as deliver.php. Comment out the require add-route.php line

<?php  
  
require_once(dirname(__DIR__,2).'/vendor/autoload.php');  
  
$lia = new \Lia();  
  
$main = \Lia\Package\Server::main($lia);  
$site = new \Lia\Package\Server($lia, 'site', __DIR__);  
  
//comment this line out in step 1  
require(__DIR__.'/add-route.php');  
  
$lia->deliver();

Write a home page.
Create a file public/index.php

<h1>Index Page</h1>  
<p>Any file in the `public` dir will be routed to automatically. Any public/*.php files are routed with NO file extension.</p>

Start the server: php -S localhost:3000 deliver.php. Visit http://localhost:3000/ in your browser

Ideally, write tests to ensure your site works as expected. See test/run/ServerMinimal.php for simple examples. I use php/tester, but Php Unit is the popular go-to for php testing

Write a view file at view/ArticlePreview.php

<div class="ArticlePreview" >  
    <h1><?=$title?></h1>  
    <p><?=$description?></p>  
</div>

Write a stylesheet at view/ArticlePreview.css
You can also write view/ArticlePreview.js and view/ArticlePreview/*.css|*.js files to add more styling and scripting

.ArticlePreview {  
    border:1px solid black;  
}

Write a route in your deliver.php file. Alternatively, make a public file public/{slug}.php and echo $view instead of $response->content = $view;

<?php  
// in production, you might use a database & have some error handling  
$articles = [  
    'cat'=>[  
        'title'=>'Cats are great',  
        'description'=>'I\'ve always loved cats. I had two when I was a little kid. As a teen I had a dog & a cat. Loved them both dearly. I love dogs too.'  
    ],  
    'dog'=>[  
        'title'=>'fill me in',  
        'description'=>'fill me in'  
    ],  
];  
  
$lia->addRoute('/{article}/',  
    function($route, $response) use ($lia, $articles){  
        $slug = $route->param('article');  
        $view = $lia->view('ArticlePreview', $articles[$slug]);  
        $response->content = $view;  
    }  
);

Write a theme at view/theme.php:

<!DOCTYPE html>  
<html>  
<head>  
<?=$this->getHeadHtml()?>  
</head>  
<body>  
<?=$content?>  
</body>  
</html>

Older Documentation

I believe the remaining docs are still accurate, but I have not reviewed them recently for accuracy or clarity.

Structure

Lia manages methods, addons, and properties
Lia\Package is a base class for packaging addons together
Lia\Addon is a base class for writing addons
Lia\Package\Server helps deliver websites by tying together main addons (public files, views, cache, autoloading, and more)
dir code/class/Object/* are objects used by built-in components
dir code/class/Utility/* are Utility classes
dir view/theme provides a default theme
dir file/mime_type_map.php is just that

Components

Addons create all the features. Lia\Package calls upon several of these components

Autoloader: loads classes within given directories
Cache: cache key/value pairs & files
Error: Report errors to users
Hook: register & call hooks (very generic form of extensibility)
Redirect: Redirect requests
Resources:
- Add css & js files, urls, and/or code blocks to a request
- Sorting api to set order of resource files in compiled output
- Routes to compiled resource files
- Manages seo information (this should go in a new component)
- Outputs headHtml (must be called)
- Passes compiled files to cache component
ResourceSorter: A wrapper around the Resources sorting api, to make it easier
Router: Set pattern & static routes. Parse paramaters from urls. Process url for route target (package, callable, file)
Server: Handles request delivery
- Helps all the addons work together to respond to a url
- delivers static non-php files
View: Display re-usable scripts/templates

Directory Structure

The Package decides the structure, so this can be changed. Default is:

App/  
    - config.json <- Package settings  
    - public/ <- Public files to be routed to. Ex: `public/contact.php` routes to `/contact/`  
    - view/ <- Views  
    - addon/ <- Addons (generally extending from \Lia\Addon)  
    - class/ <- Classes to autoload, PSR4 style. Will be converted to classmap style later  
    - cache/ <- Dir to store cache files. Only one cache dir is used (each app does not get its own)

Other Stuff

Environment-dependent features are not built-in, but I recommend my php/env

Taeluf.com