html_first/atla-as

php file system routing, file serving, connection and SQL DB querying library

2.0.0 2025-03-14 06:06 UTC

Requires

• php: >=8.0.0

MIT

• Hakim Jazuli

README

• php:

• file system routing;

• setting up middleware;

• file serving;

• connection and SQL DB querying library;

• this library is designed to be used in the conjuction with our client side HATEOAS sister

library https://github.com/hakimjazuli/atlaAS_client in mind;

• however you can still uses it as Backend normally for, like:

• building REST json api backend: using our "HtmlFirstatlaASMiddlewares_Middleware",

to set up header default header on /api/** routes;

• serving files: using our "HtmlFirstatlaASRouter_MapResources;";

• building HATEOAS backend for htmx/other HATEOAS library/framework;

• in fact you might be surprissed how good File System Routing might fare for

htmx/other HATEOAS library due to the nature of atlaAS code splitting in general;

• automatic routes setup;

• no need to register it using framework class instances first;

• in htmx use case, you can even opt out from using hx-select and/or hx-target as

the returned html needed are easily split per routes file;

• not to mention how php is a natural templating language for html _(well... if

there's any more natural language, php is still the most easiest to set up, "there's no setup", just use ?> to enter front end and <?php to go back to backend)_

• just make sure to sanitize your output, so you don't get XSS attack from user

generated content;

assumption

this library assumes you are familiar with:

• php psr-4 auto-loading, using composer;

• php OOP(for extending, and using our helper classes in general, also atlaAS uses little

abstraction, and not neccesarily a battery-included library, so you have to have good

underlying php OOP in generals);

how to install

composer require html_first/atla-as

how to initialize

set your .htaccess on your static public folder into something like this:

<IfModule mod_rewrite.c>

	SetEnvIf Origin "^http(s)?://(.+.)?(127.0.0.1:8000)$" ACAO=$0

	# SetEnvIf Origin "^http(s)?://(.+.)?(127.0.0.1:8000|172.23.224.1:8000)$" ACAO=$0

	Header set Access-Control-Allow-Origin "%{ACAO}e" env=ACAO

		<IfModule mod_negotiation.c>

			Options -MultiViews -Indexes

		</IfModule>

	RewriteEngine On

	# Handle Authorization Header

	RewriteCond %{HTTP:Authorization} .

	RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

	# Redirect Trailing Slashes If Not A Folder...

	RewriteCond %{REQUEST_FILENAME} !-d

	RewriteCond %{REQUEST_URI} (.+)/$

	RewriteRule ^ %1 [L,R=301]

	# Send Requests To Front Controller...

	RewriteCond %{REQUEST_FILENAME} !-d

	RewriteCond %{REQUEST_FILENAME} !-f

	RewriteRule ^ index.php [L]

</IfModule>

Credit(s)

this library is inspired by:

• htmx.js: https://htmx.org/

• more precisely it's HATEOAS paradigm in general;

• sveltekit: https://kit.svelte.dev/

• more precisely it's clean File System Routing in general;

• and many other js meta framework with FS Routing;

Globals

• class prefixed "__" with are singleton made globals by accessing it like this __ClassName::$__;

Setting_Class

• class that are need to be extended, instantiated as argument for __atlaAS

• modifiy it's properties and methods as you needed

Internals

• core class that are meant to be used only for library internals functionality and not to be called on the app;

exported-api-by-namespace

• HtmlFirst\atlaAS\Connection\Conn

• HtmlFirst\atlaAS\Connection_atlaASQuery

• HtmlFirst\atlaAS\connection_Binder

• HtmlFirst\atlaAS\Connection_FieldType

• HtmlFirst\atlaAS\Connection_Query

• HtmlFirst\atlaAS\Connection_Table

• HtmlFirst\atlaAS\Middlewares\FSMiddleware

• HtmlFirst\atlaAS\Middlewares_Middleware

• HtmlFirst\atlaAS\Router\FSRouter

• HtmlFirst\atlaAS\Router_MapResources

• HtmlFirst\atlaAS\Router_Routes

• HtmlFirst\atlaAS\Router_RoutesWithMapResources

• HtmlFirst\atlaAS\Router_RoutesWithMapResourcesAndMiddleware

• HtmlFirst\atlaAS\Router_RoutesWithMiddleware

• HtmlFirst\atlaAS\Utils\Validate

• HtmlFirst__atlaAS\Utils\VideoStream

• HtmlFirst\atlaAS\Utils_Cors

• HtmlFirst\atlaAS\Utils_FileServer

• HtmlFirst\atlaAS\Utils_FunctionHelpers

• HtmlFirst\atlaAS\Utils_GlobalVar

• HtmlFirst\atlaAS\Utils_Hasher

• HtmlFirst\atlaAS\Utils_Is

• HtmlFirst\atlaAS\Utils_Temp

• HtmlFirst\atlaAS\Utils__Request

• HtmlFirst\atlaAS\Utils__Response

• HtmlFirst\atlaAS\Vars__Env

• HtmlFirst\atlaAS\Vars__Settings

• HtmlFirst\atlaAS\Vars__SQLite3

• HtmlFirst\atlaAS__atlaAS

HtmlFirst\atlaAS\Connection\Conn

• containt static methods for connection helpers;

*) _{go to exported list}

HtmlFirst\atlaAS\Connection\_atlaASQuery

• type generator for _Query

*) _{go to exported list}

HtmlFirst\atlaAS\connection\_Binder

*) _{go to exported list}

HtmlFirst\atlaAS\Connection\_FieldType

• internal class helper for _Query;

*) _{go to exported list}

HtmlFirst\atlaAS\Connection\_Query

• query helper

<?php
namespace Backend\Queries;
use Backend\Tables\Test as TablesTest;
use HtmlFirst\atlaAS\Connection\_atlaASQuery;
use HtmlFirst\atlaAS\Connection\_Query;
class Test extends _Query {
   public static function test_name_like(string $test_name): _atlaASQuery {
       $test = new TablesTest;
       return self::sql_query('/sql/views/test.sql', bind: [
           ... new HtmlFirst\atlaAS\connection\_Binder(...$args),
       ]);
   }
}

• setting up /sql/views/test.sql

SELECT
`id`,
   test.test_name
FROM
   test
WHERE
   `test_name` LIKE :test_name;

*) _{go to exported list}

HtmlFirst\atlaAS\Connection\_Table

• extend this class for sql table templating;

• assign all property type as \HtmlFirst\atlaAS\Connection_FieldType;

• eg. public _FieldType $field_name_alias;

• then on constructor assign it by calling $this->column(...$neccessary_args);

• table helper

<?php
namespace Backend\Tables;
use HtmlFirst\atlaAS\Connection\_FieldType;
use HtmlFirst\atlaAS\Connection\_Table;
use PDO;
class Test extends _Table { 
   public _FieldType $id;
   public _FieldType $name;
   public function __construct() {
       $this->id = $this->column(PDO::PARAM_INT);
       $this->name = $this->column(PDO::PARAM_STR, $this->regex_alphanumeric_loose(1, 255));
   }
}

*) _{go to exported list}

HtmlFirst\atlaAS\Middlewares\FSMiddleware

• internal class

*) _{go to exported list}

HtmlFirst\atlaAS\Middlewares\_Middleware

• class helper to validate mw.php and _Routes derived class which also have Middleware in it's name;

<?php

namespace Routes\api;

use HtmlFirst\atlaAS\Middlewares\_Middleware;

class mw extends _Middleware {
   public function mw(string $method): bool {
       \header('Content-Type: application/json');
       }
       return true; /** return true to continue response */
}

• folder structure

• routes

• index.php
• api

• mw.php <-- this is middleware file

• which then turns all of your /api/** routes suitable for json api server;

*) _{go to exported list}

HtmlFirst\atlaAS\Router\FSRouter

• internal class

*) _{go to exported list}

HtmlFirst\atlaAS\Router\_MapResources

<?php
namespace Routes;
use HtmlFirst\atlaAS\Router\_MapResources;
class assets extends _MapResources {
}

your folder should then looks like this

• routes

• assets.php
• assets

  • atlaAS.mjs
  • main.css

• you can overwrite map_resources method to use it as additional middleware to get the list of uri array request;

• although you might not output anything as it will bug the headers for file range;

• your intellisense warning is your friend;
• _MapResources Routes's map_resources method uses spread parameters;
• don't worry, it will NOT serve your .php files( or any file extentions, listed in extended __Settings $system_file);

*) _{go to exported list}

HtmlFirst\atlaAS\Router\_Routes

• using extended __Settings class you can change

• folder: __Settings class property $routes_path
• namespace: __Settings class property $routes_class

• routes naming:

• have to be the same with the class name(case-sensitve), preferably lowercase
• method are public function http-method(lower case) with parameters of the dynamic uri's;
• bellow are available on '/example/test/my_name/my_num' url, will result in echoing "my_name, my_num"

<?php
namespace Routes\example;
use HtmlFirst\atlaAS\Router\_Routes;
class test extends _Routes {
   public function get(string $name, string $num) {
       echo "$name, $num";
   }
}

• routes naming:

• you have to extend it from

• "HtmlFirst\atlaAS\Router\_Routes;"
• "HtmlFirst\atlaAS\Router\_RoutesWithMiddleware;"

*) _{go to exported list}

HtmlFirst\atlaAS\Router\_RoutesWithMapResources

• derived from:

• HtmlFirst\atlaAS\Router_Routes;
• HtmlFirst\atlaAS\Router_MapResources;

*) _{go to exported list}

HtmlFirst\atlaAS\Router\_RoutesWithMapResourcesAndMiddleware

• derived from:

• HtmlFirst\atlaAS\Middlewares_Middleware;
• HtmlFirst\atlaAS\Router_Routes;
• HtmlFirst\atlaAS\Router_MapResources;

*) _{go to exported list}

HtmlFirst\atlaAS\Router\_RoutesWithMiddleware

• derived from:

• HtmlFirst\atlaAS\Middlewares_Middleware;
• HtmlFirst\atlaAS\Router_Routes;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\Validate

• internal class helper;

*) _{go to exported list}

HtmlFirst\__atlaAS\Utils\VideoStream

• a modified VideoStream helper which the original I got from

<?php
/** 
* @author Rana modified by HS
* @link http://codesamplez.com/programming/php-html5-video-streaming-tutorial
*/

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_Cors

• contains static method(s) to handle cors policy;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_FileServer

• contains method(s) for file serving related functionalities;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_FunctionHelpers

• contains method(s) for php general variable handling functionalities;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_GlobalVar

• class helper to use __atlaAS::$__->global feature;
• lookup at HtmlFirst\atlaAS\Utils_Is for example

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_Hasher

collection of static methods for hashing purposes;

• html_csrf_element: for generating string element of csrf;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_Is

• an example to use HtmlFirst\atlaAS\Utils_GlobalVar:

<?php
class _Is extends _GlobalVar {
   protected static string $global_namespace = 'is';
   public static function atlaAS_client_request(_Routes $_routes): false|string {
       if (!$_routes->is_real_route) {
           return false;
       }
       $atlaAS_client_request_header = __Request::valid_request_header('atlaAS_client_form'); // 1
       if (isset($_SERVER[$atlaAS_client_request_header])) {
           return self::global($atlaAS_client_request_header, $_SERVER[$atlaAS_client_request_header]); // 2
       }
       return false;
   }
}

• 1 generate valid http request header for atlaAS_client_from in this case HTTP_ATLAAS_CLIENT_FORM;
• 2 can be used to access (and assign at the same time) atlaAS::$::$global associative array, which then be used down the line of current request;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\_Temp

• static method var of this class to be used to hold temporary value onto reference, which then returns a callable, to return the value before calling var; ?> - var_reference the first argument is a pointer;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\__Request

• this class is global singelton
• altough this class are global singleton all methods and properties are public static;
• this class contains several values that contains incoming request variables;

*) _{go to exported list}

HtmlFirst\atlaAS\Utils\__Response

• this class is global singelton
• altough this class are global singleton all methods and properties are public static;
• this class contains several common methods to handle response to client;

*) _{go to exported list}

HtmlFirst\atlaAS\Vars\__Env

• this class is a global singelton;
• this class is a setting class;
• overwrite this public function pdo;

*) _{go to exported list}

HtmlFirst\atlaAS\Vars\__Settings

• this class is a global singelton;
• this class is a setting class;

*) _{go to exported list}

HtmlFirst\atlaAS\Vars\__SQLite3

• this class is a global singelton;
• this class is a setting class;

*) _{go to exported list}

HtmlFirst\atlaAS\__atlaAS

• this class is global singelton
• use this class as entry point;
• instantiate it, with extended __Env, __Settings, __SQLite3* as arguments;
• then call run method;

// /your_public_root/index.html
<?php

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

(new \Backend\__atlaAS(
    new \Backend\__Env,
    new \Backend\__Settings,
    new \Backend\__SQLite3,
))->run();

*) _{go to exported list}