Taeluf.com

Liaison App (aka Package)

A Liaison app can include routes, views, methods, hooks, and more. You can include as few or as many parts as you like.

Apps typically do one of two things: create features for other apps to use or implement features other apps provide. Most features are created through Addons. Most features are implemented through directory structures & configurations.

Also See:

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

Sections of this document

  • Directory Structure
  • config.json
  • Routing
    • Files
    • addRoute()

TODO:

  • Views
  • Addons
  • Hooks
  • Seo Headers
  • Css & Javascript files

App Directory Structure

You can include one, multiple, or all of these files & directories.

App/  
    - config.json <- Package settings  
    - public/ <- Public files to be routed to.   
        - index.css  
        - index.php <- home page  
        - contact.php <- /contact/  
    - view/ <- Views  
        - theme.php <- site layout  
        - theme.css  
    - addon/ <- Addons (extend \Lia\Addon)  
        - MyAddon.php  
    - class/ <- Classes to autoload, PSR4 style, but you should use composer instead.

Note: You don't need to make any files until you're ready for them.

config.json

config.json is optional & there are likely to be breaking changes.

{  
    "namespace": "lia",  
    "name": "lia",  
    "fqn": "lia:server",  
    "base_url": "/",  
    "public_file_params": {  
        "key":"raw_value"  
    }  
}

Notes:

  • namespace does nothing currently. It was supposed to, but we're actually using name and fqn. We will likely change this.
  • the Server package loads the configs & for any config that has a matching property on the package class will overwrite that property.

Routing

Routing is available through your public dir, and through $lia->addRoute('/pattern/{slug}/', callable).

To test:

  1. Create deliver.php following the Web Server Documentation
  2. php -S localhost:3000 /deliver.php

/public/ Files

/public/index.php: (Your home page /)

<?php  
    // add a css (or js) file to the page. Files of the same type are compiled together.  
    $lia->addResourceFile(__DIR__.'/index.css');  
    // public_file_params from your config.json are available here   
?>  
  
<h1>Elections in My Town, Some State</h1>  
<p>My Town's city council & school board elections are approaching soon! The school board race is cotentious with only 3 seats available, but 7 candidates running - some with very different perspectives. ...</p>  
  
<?php   
// $lia->view('elections.php', $args=[]); # We'll use this later.  
?>

/public/index.css:

h1 {  
    font-size:1.6em;  
    margin:0;  
    padding:8px;  
}  
p {  
    max-width: 80ch;  
    padding: 12px;  
}

Visit http://localhost:3000/.

Note: Public files can also use patterns, like public/election/{slug}/, just like programmatic routes below.

$lia->addRoute()

Routes can be added programmatically with or without paramaters, and can point to a callable or a file.

Also See:

<?php  
// \Lia $lia  
$lia->addRoute('/election/2023-city-council/',   
    function(\Lia\Obj\Route $route,\Lia\Obj\Response $response) use ($lia){  
        $response->content = $lia->view('office', ['year'=>'2023', 'election'=>'city-council']);  
    }  
);  
  
// or you can use paramaters  
$lia->addRoute('/election/{year}/{$name}/',   
    function(\Lia\Obj\Route $route,\Lia\Obj\Response $response) use ($lia){  
        $response->content = $lia->view('office',   
            [  
                'year'=>$route->param('year'),   
                'election'=>$route->param('name')  
            ]  
        );  
    }  
);  
  
//optional paramaters don't have to be at the end.  
$lia->addRoute('/candidate/{uuid}/{?slug}/', ...);  
  
// only allow post requests (also works with a callable)  
$lia->addRoute('@POST./submit_voter_opinion/', 'path/to/some/file.php');  
  
// allow get & post  
$lia->addRoute('@GET.@POST./candidate_questionnaire/', 'path/to/some/file.php');

Notes:

  • Routes are retrieved from Lia\Addon\Router, and processed in Lia\Addon\Server; see process_route().
  • addRoute accepts a third paramater, which is passed to files as the variable $package; it is not available in callable routes.

Views - /view/

View Directories

  • view help/errors resides at $view_dir.'/help/errors.php' and may have errors.css and errors.js next to it that will be automatically included
  • TODO: Document more and better

Add Views

  • Add view files into existing view directories
  • $lia->addon('lia:server.view')->addViewFile('view_name', 'path/to/file.php'), file.php should output content
  • or $lia->addon('lia:server.view')->addViewCallable('view_name', function(string $view_name, array $args){ return 'content';});
  • or $lia->addon('lia:server.view')->addView('view_name', '/views/directory/')

Addons Lia\Addon

TODO - fill in view docs for libraries

Hooks

Hook into an event:

<?php  
// DASHBOARD_DISPLAYED is a string constant and is part of another library   
$lia->hook(\Tlf\User\Hooks::DASHBOARD_DISPLAYED,  
    // Each hook defines it's own function signature (essentially by passing the correct paramaters when calling the hook)  
    function(\Lia $lia, \Tlf\User\EasyServer $server){  
        // may contain css to switch to a full-width page to better display the dashboard  
        $lia->addResourceFile(dirname(__DIR__).'/file/user-dashboard.css');  
    }  
);  
  
// Alternatively:  
// $lia->addon('lia:server.hook')->add(DASHBOARD_DISPLAYED, function(){});

Call a hook:

<?php  
// each arg after the hook name is passed directly to each registered callable.  
$lia->call_hook(\Tlf\User\Hooks::DASHBOARD_DISPLAYED, $lia, $easy_user_server);  
  
// Alternatively:  
// $lia->addon('lia:server.hook')->call(DASHBOARD_DISPLAYED, $lia,$easy_user_server);

SEO Headers

TODO

Css & Javascript files

TODO