README

Phad: Php Html Api Database

Write HTML templates and auto-fill it from the database. Generate routes, handle form submissions with validation, and even validate logged-in-users all through HTML (and a little SQL). Your Templates can include PHP but it is often not necessary.

The templates you write are compiled into PHP scripts to improve runtime performance.

NOTICE: The latest working version is branch v0.4. This branch is NOT READY. The documentation represents what I WANT, not what is actually functional right now.

TODO:

Write good documentation
create interfaces for required integrations
add integrations for Liaison and my User Login libraries
Maybe add interface and integration for database access.
Remove Liaison requirement (convert it to recommended, and integration should be with v0.7).
Add default access handlers that do nothing in order to allow simple setups where full access is given.

Install

composer require taeluf/phad v1.0.x-dev

or in your composer.json

{"require":{ "taeluf/phad": "v1.0.x-dev"}}

Documentation

Getting Started (below): Standard setup integrating with Liaison and my User Login library.
TODO Loading Data: Load data into your views and forms, whether from the database or manually loaded. Optionally load your data into ORMs.
TODO Routing and Sitemaps: Create routes to your views and forms, and add them to your sitemap.
TODO Property Filters: Convert the database-value of properties into desired format.
TODO Handling Errors: Handle expected errors, such as data-not-available or access-not-allowed
TODO Form Validation: Validate values submitted via forms
TODO Form Hooks: onsubmit, failsubmit, and didsubmit hooks for forms
TODO Controll Access: Manage access to views, forms, and data based on logged-in user

Getting Started

Phad (class Phad) provides accesss to Items (class Phad\Item) and integrates them with your router, the form validator, property filters, database, form submitter, spam controller, sitemap generator, and user access layer. An Item represents a single HTML template file, which is compiled into a PHP script with Phad\DOMParser and Phad\TemplateCompiler.

There is built-in integration with Liaison for routing, but you may write your own routing integration. You must write integration for user-based access controls or provide full access to all items. You may add custom property filters and override the database-access layer. You will have to write SQL queries to load data into your views.

Docs Below

Server Setup
Example Item Template
Example Form
Generate SQL from your form
Next Steps

Server Setup

This setup uses Liaison for routing and my User Login library for access controls. You can write a custom Router Class and Access Class for other setups. You may use \Phad\Integration\DynamicAccess as your Access class for simple read-only setups, or use it as a base class and modify only what you need.

/deliver.php: (or wherever you initialize your server)

<?php   
  
// Setup Liaison and User Library  
  
$root_dir = __DIR__;  
$pdo = new \PDO(...);  
$configs = [...]; // configs are optional  
  
$phad = \Phad::custom(  
    $pdo,  
    $root_dir, // $dir will contain sub-dirs `phad/`, `sitemap/`, and `cache/` by default  
    new \Phad\Integration\LiaisonRouter($liaison),  
    new \Phad\Integration\TlfUserAccess($user_package),  
    $configs  
);  
  
// $phad->throw_on_query_failure = false; # true by default. Set false for queries to fail silently.  
// $phad->force_compile = true; # false by default. Set true while developing and debugging to always re-compile items.

Configuration: See (error: link "src/defaults.json" not found*). You can either make your own .json config file or write the config array directly in PHP (json is better if you want different configs in different environments).

Note: *For Liaison & TLF User integration, you may call Phad::main($pdo, $root_dir, $liaison, $user_package, $configs) instead of custom(...).

Example Item Template

This creates a route to /blog/{slug}/. When the route is requested, the <p-data> node's where is used to build the SQL query. The {slug} from the route is automatically bound to :slug in the where statement.

The <h1> is filled with the blog's title, and the <x-prop> node is replaced with the blog's html_body. (<x-prop itself is not rendered`)

<route pattern="/blog/{slug}/"></route>    
<div item="Blog">    
    <p-data where="Blog.slug LIKE :slug"></p-data>    
    <h1 prop="title"></h1>    
    <x-prop prop="html_body"></x-prop>  
</div>

Example Form

GET /form/blog/ will display this form. If ?id=37 is passed, then the blog post with id=37 will automatically be filled into the form.

GET /form/blog/?phad_action=delete&id=37 will DELETE the blog post with id=37 ONLY if candelete attribute is added to the <form node AND candelete handler returns true. (Note: This functionality WILL change because DELETE operations should never be over GET, and should never be performed without CSRF validation)

POST /form/blog/ will save the blog post to database, whether INSERTing a new article, or UPDATEing an existing one.

<route pattern="/form/blog/"></route>    
<form item="blog" target="/blog/{slug}/">    
    <onsubmit><?php    
        $articleRow['slug'] = \YourNamespace\slugify($articleRow['title']);  
    ?></onsubmit>    
  
    <input type="text" name="title" maxlength="75" />    
    <textarea name="body" maxlength="1500"></textarea>  
  
    <input type="submit" value="Submit" />  
    
    <input type="hidden" name="id" />    
      
    <!-- The `backend` type allows the form validation to permit slug being added during `onsubmit` -->  
    <input type="backend" name="slug" />  
</form>

<onsubmit> is a hook that will be executed during submission BEFORE any INSERT/UPDATE operation, allowing you to add a slug or make other modifications before database entry.

Additional hooks are available.

Generate SQL from your form

You can generate an SQL CREATE TABLE statement based on a form you create. You should review that statement and modify as needed, and should store it on-disk in your project. My preferred database library is BigDb (which I developed).

(Currently, you call Item::create_table_statement())

To generate SQL:

TODO: create bin script

taeluf / phad

Maintainers

Details