Skip to content

README.md

Latest commit

 

History

History
240 lines (179 loc) · 7.77 KB

README.md

File metadata and controls

240 lines (179 loc) · 7.77 KB
Raw

COSMOS

Contributor Covenant Conventional Commits GitHub Semantic Versioning
Gitleaks Discord

About

Aurora is a lightweight PHP HTML5 template engine built for rapid deployment of sites with AJAX content loading. It targets modern HTML specifications and web standards.

This has been created with personal use in mind and is highly tailored to the types of sites I create and run. That said, this could be easily adapted to anyone's needs with a bit of work.

Requirements

  • PHP 8.5 or later
  • MariaDB / MySQL (for the SQL handler)
  • Composer

What's Included

  • Template-based HTML header with {{ var }} / {% func() %} syntax
  • Resource preloading with DNS prefetch and preconnect
  • Subresource Integrity (SRI) — sha512 hashes with cache-busting versions
  • CSS stylesheet injection
  • JavaScript injection (regular scripts and ES modules)
  • External script support for third-party resources
  • Custom template overlay with fallback to default
  • Open Graph meta tags
  • Performance statistics (CPU time, version info)
  • PDO-based SQL handler with prepared statements
  • Custom exception handling (AuroraException)

Installation

Add Aurora as a git submodule in your project:

git submodule add https://github.com/kyaulabs/aurora.git aurora

Copy and configure the database settings:

cp aurora/settings.example.php aurora/settings.inc.php

Edit settings.inc.php with your MariaDB/MySQL credentials.

Usage

<?php
# $KYAULabs: index.php,v 1.0.0 2026/06/28 00:00:00 -0700 kyau Exp $

$rus = getrusage();
require_once(__DIR__ . "/../aurora/aurora.inc.php");

$site = new KYAULabs\Aurora("index.html", "/cdn", true, true);
$site->title = "Page Title";
$site->description = "Page description for search engines.";
$site->dns = ["cdn.domain.com"];
$site->css = [
    'css/site.min.css' => '//cdn.domain.com/css/site.min.css',
];
$site->preload = [
    '/css/site.min.css' => 'style',
];
$site->js = [
    'javascript/site.min.js' => '//cdn.domain.com/javascript/site.min.js',
];
$site->mjs = [
    'javascript/app.min.js' => '//cdn.domain.com/javascript/app.min.js',
];

$site->htmlHeader();
// page content
echo "\t<header></header>\n\t<main></main>\n\t<footer></footer>\n";
$site->htmlFooter();
echo $site->comment($rus, $_SERVER['SCRIPT_FILENAME'], true);

Template System

Templates are plain HTML files stored in aurora/html/. The default template (index.html) uses two placeholder syntaxes:

  • {{ variable_name }} — replaced with scalar values set on the $site object (e.g. $site->title = "Hello" fills in {{ title }})
  • {% func() %} — replaced with generated HTML from internal methods:
Tag Output
{% css() %} <link rel="stylesheet"> tags with SRI
{% preload() %} <link rel="dns-prefetch">, <link rel="preconnect">, and <link rel="preload"> tags

Note: JavaScript is injected by htmlFooter(), not from the template. The closing </body> and </html> tags are also emitted by htmlFooter().

Template Overlay

The constructor accepts an optional 5th parameter for a custom template directory. If a template file exists there, it is used; otherwise the default aurora/html/ template is the fallback:

$site = new KYAULabs\Aurora("index.html", "/cdn", true, true, __DIR__ . "/templates");

This lets you override the default template per-project without modifying Aurora.

External Scripts

For third-party scripts that shouldn't be hashed (e.g. analytics, CAPTCHA), use the <external> key:

$site->js = [
    '<external>' => 'https://third-party.com/script.js',
];
$site->mjs = [
    '<external>' => 'https://third-party.com/module.js',
];

External scripts are auto-assigned sequential id="ext1", id="ext2", etc.

Constructor Reference

new KYAULabs\Aurora(
    ?string $template,     // template filename (e.g. "index.html")
    ?string $cdn,          // CDN directory path relative to webroot (default: '/cdn')
    bool $status,          // enable verbose error display in browser
    bool $html,            // set Content-Type header to text/html
    ?string $templateDir   // custom template overlay directory (optional)
)

Properties

Set properties on the $site object using assignment syntax:

Property Type Description
$site->title string Page title (<title> and og:title)
$site->description string Meta description and og:description
$site->dns array Domains for DNS prefetch/preconnect tags
$site->css array Path-to-URL map for stylesheets
$site->js array Path-to-URL map for JavaScript files
$site->mjs array Path-to-URL map for JavaScript ES modules
$site->preload array URL-to-type map for resource preloading

Any other property name is stored as a template variable for {{ var }} substitution. Custom template variables must be set before calling htmlHeader().

Methods

Method Description
htmlHeader() Renders the template header
htmlFooter() Emits <script> tags and closes </body></html>
comment($rus, $script, $vim) Returns an HTML comment with version and performance stats
version($script) Returns the version string from a file's RCS header
testVariables() Debug: reports which template variables were successfully replaced

SQL Handler

Aurora includes a PDO-based MariaDB/MySQL handler with real prepared statements and utf8mb4 charset.

Configuration

  1. Copy settings.example.php to settings.inc.php
  2. Edit the constants with your database credentials:
define("SQL_HOST", "127.0.0.1");       // optional — defaults to 127.0.0.1
define("SQL_PORT", 3306);              // optional — defaults to 3306
define("SQL_SOCKET", "/run/mysqld/mysqld.sock"); // Linux-only; remove on Windows
define("SQL_USER", "username");
define("SQL_PASSWD", "password");

settings.inc.php is .gitignored — never commit database credentials.

Basic Usage

require_once(__DIR__ . "/../aurora/sql.inc.php");

$db = new KYAULabs\SQLHandler("my_database");

// prepared statement with named parameters
$stmt = $db->query("SELECT * FROM users WHERE id = :id", [':id' => 42]);
while ($row = $stmt->fetch()) {
    echo $row['username'];
}

// switch databases
$db->setDatabase("other_database");

Error Modes

Set the error handling mode by modifying the protected $err property:

Constant Behavior
SQLHandler::INTERNAL_HANDLING Display/log the error (default)
SQLHandler::THROW_EXCEPTION Re-throw PDOException for custom handling
SQLHandler::IGNORE_ERRORS Silently ignore errors

Development

Testing

Tests use Pest PHP:

php vendor/bin/pest
php vendor/bin/pest --coverage     # with coverage report

Linting

# PHP syntax check
php -l file.php

# PHP code style (PSR-12)
php-cs-fixer fix . --dry-run --diff