library_books Core Library Reference

Comprehensive documentation for all BoomStick core libraries.

menu_book Libraries
Globals Controller Route Request Session Debug Struct CLI Database Session Drivers

public Globals

The Globals class provides static access to core framework objects. Aliased as G throughout the framework.

description lib/Globals.class.php 
use BoomStick\Lib\Globals as G;

// Available static properties
G::$debug;    // boolean - Debug mode flag
G::$route;    // Route object - Current route instance
G::$request;  // Request object - HTTP request data
G::$session;  // Session object - Session management
G::$version;  // string - Framework version
Usage Examples
use BoomStick\Lib\Globals as G;

// Access the current request path
$path = G::$request->getRequestedPath();

// Get route parameters
$params = G::$route->getParameters();

// Check if in debug mode
if (G::$debug) {
    // Debug-only code
}

// Access session data
$userId = G::$session->userId;

settings_remote Controller

The Controller class is the base class for all module controllers. It provides methods for rendering views, elements, styles, and scripts.

description lib/Controller.class.php
Class Definition
namespace BoomStick\Lib;

abstract class Controller extends ControllerAPI
{
    // Magic methods for variable assignment
    public function __get($key);
    public function __set($key, $value);
    
    // Layout methods
    public function setLayout($layout = 'default', $moduleOverride = null): void;
    
    // Render methods
    public function render();
    public function renderReturn();
    public function renderView($file);
    public function renderViewCSS($file);
    public function renderViewXML($file);
    public function renderViewTXT($file);
    
    // Insert methods (for use in templates)
    public function insertElement($file);
    public function insertView($file);
    public function insertStyle($file);
    public function insertScript($file);
    public function insertRoute($name, $parameters);
}
Key Methods
Method Description
render() Outputs the layout with the assigned view to the browser
renderReturn() Returns the rendered content as a string instead of outputting
setLayout($layout) Sets a custom layout file (default: 'default')
insertView($file) Includes and returns content from a view file
insertElement($file) Includes and returns content from an element file
insertStyle($file) Includes inline CSS from a style file
insertScript($file) Includes inline JavaScript from a script file
Usage Example
namespace BoomStick\Module\MyModule\Controller;
use BoomStick\Lib\Controller;

class MyModule extends Controller
{
    public function index()
    {
        // Pass variables to the view
        $this->pageTitle = 'Welcome';
        $this->users = $this->fetchUsers();
        
        // Set which view to render
        $this->bodyView = 'index';
        
        // Render the output
        $this->render();
    }
    
    public function apiEndpoint()
    {
        $this->data = ['status' => 'success'];
        $this->bodyView = 'api-response';
        
        // Render as JSON (in view: echo json_encode($data))
        header('Content-Type: application/json');
        $this->render();
    }
}

alt_route Route

The Route class handles URL routing, mapping URL paths to controller actions with support for parameters and named routes.

description lib/Route.class.php
Key Methods
class Route
{
    // SEO Constants
    const SEO_CANONICAL     = 'seo_canonical';
    const SEO_NO_INDEX      = 'seo_no_index';
    const SEO_USE_PERMALINK = 'seo_use_permalink';
    
    // Route registration
    public function register($route, $alias, $seoType = null): RouteName;
    
    // Named route lookup
    public function byName($name, $parameters = []);
    
    // Route information
    public function getParameters();
    public function getOriginalPath();
    public function getCanonicalPath();
    public function modulePath();
    public function moduleBasename();
    public function controllerAction();
}
Route Registration
$route = new MyModule();

// Basic route
$route->register('MyModule/index', '/');

// Route with named reference
$route->register('MyModule/show', '/products/%i')
    ->name('product-detail');

// Route with string parameter
$route->register('MyModule/category', '/category/%s')
    ->name('category-page');

// POST-only route
$route->register('MyModule/save', '/api/save')
    ->name('api-save')
    ->POST();

// GET-only route  
$route->register('MyModule/list', '/api/list')
    ->name('api-list')
    ->GET();
Parameter Placeholders
Placeholder Type Pattern
%i Integer [0-9]+
%s String [a-zA-Z0-9\-\.\%\@_\=\s]+
Using Named Routes in Templates
use BoomStick\Lib\Globals as G;

// In a view or element file:
<a href="<?=G::$route->byName('product-detail', [123]);?>">
    View Product #123
</a>

// Output: <a href="/products/123">View Product #123</a>

http Request

The Request class provides access to HTTP request data including parameters, methods, and headers.

description lib/Request.class.php 
class Request
{
    // Access request parameters (GET/POST)
    public function __get($name);
    public function __isset($name);
    
    // HTTP method checks
    public function getMethod();
    public function isPOST();
    public function isGET();
    public function isPUT();
    public function isDELETE();
    public function isAJAX();
    
    // Request data
    public function getRequestedPath();
    public function getProtocol();
    public function getHostConfig();
    public function getPOST();
    public function getJSON();
    public function refererRoute();
}
Usage Examples
use BoomStick\Lib\Globals as G;

// Access GET/POST parameters
$id = G::$request->id;
$name = G::$request->name;

// Check request method
if (G::$request->isPOST()) {
    $data = G::$request->getPOST();
    // Process form submission
}

// Handle JSON API requests
if (G::$request->isAJAX()) {
    $json = G::$request->getJSON();
    // Process JSON payload
}

// Get the current path
$path = G::$request->getRequestedPath();

// Check protocol
$protocol = G::$request->getProtocol(); // 'http' or 'https'

vpn_key Session

The Session class provides session management with support for CSRF tokens and secure session handling.

description lib/Session.class.php 
class Session extends Struct
{
    // Status constants
    const STATUS_ACTIVE   = 'ACTIVE';
    const STATUS_NONE     = 'NONE';
    const STATUS_DISABLED = 'DISABLED';
    
    // Constructor
    public function __construct(
        $name = '__boomstick_sid__',
        $type = 'local',
        $lifetime = 315360000  // 10 years
    );
    
    // Session data access
    public function __get($key);
    public function __set($key, $value);
    public function __isset($key);
    public function all();
    
    // Security tokens
    public function URLToken();
    public function CSRFToken();
    
    // Persistence
    public function save();
}
Usage Examples
use BoomStick\Lib\Globals as G;

// Store session data
G::$session->userId = 123;
G::$session->userName = 'john_doe';
G::$session->isLoggedIn = true;

// Retrieve session data
$userId = G::$session->userId;

// Check if session variable exists
if (isset(G::$session->isLoggedIn)) {
    // User is logged in
}

// Get all session data
$allData = G::$session->all();

// Get CSRF token for forms
$token = G::$session->CSRFToken();

// In your form template:
<input type="hidden" name="csrf_token" value="<?=G::$session->CSRFToken();?>">

bug_report Debug

The Debug class provides debugging utilities including console logging, timers, and variable inspection. Aliased as D.

warning Important: Debug methods only work when G::$debug = true. In production, they are disabled or throw exceptions.
description lib/Debug.class.php 
use BoomStick\Lib\Debug as D;

class Debug
{
    const ISOLATE = 1;
    
    // Console output (requires console listener)
    public static function console($data, $showBacktrace = false, $port = 8000);
    public static function consoleIsolated($switch, $data, $showBacktrace = false, $port = 8000);
    
    // Timer for performance profiling
    public static function timer($id, $showBacktrace = false, $port = 8000);
    
    // Print to browser
    public static function printr($variable, $halt = false, $showBacktrace = false);
    public static function printre($variable, $showBacktrace = false);  // Print and exit
    
    // Get backtrace
    public static function backtrace();
}
Usage Examples
use BoomStick\Lib\Debug as D;

// Print variable and continue
D::printr($myArray);

// Print variable and halt execution
D::printre($myObject);

// Print with full backtrace
D::printr($data, false, true);

// Console logging (requires console listener on port 8000)
D::console($debugData);
D::console($debugData, true);  // With backtrace

// Performance timing
D::timer('database-query');
// ... database operations ...
D::timer('database-query');  // Logs time since first call

schema Struct

The Struct class is a base class that enforces strict property access, preventing access to undefined properties.

description lib/Struct.class.php 
class Struct
{
    public function __get($invalidAttribute)
    {
        throw new \ErrorException(
            'Trying to access an invalid attribute Struct::' . $invalidAttribute
        );
    }

    public function __set($invalidAttribute, $value)
    {
        throw new \ErrorException(
            'Trying to write to an invalid attribute Struct::' . $invalidAttribute
        );
    }
}
Usage Example
use BoomStick\Lib\Struct;

class UserConfig extends Struct
{
    public $name;
    public $email;
    public $role = 'user';
}

$config = new UserConfig();
$config->name = 'John';     // OK
$config->email = 'j@x.com'; // OK

$config->invalid = 'test';  // Throws ErrorException!
echo $config->missing;      // Throws ErrorException!
info Tip: Use Struct as a base class for configuration objects, DTOs, or any class where you want strict property enforcement.

terminal CLI

The CLI library provides tools for building command-line scripts with argument parsing, flags, options, and colorized output.

folder lib/cli/ 
lib/cli/
├── CLI.class.php       # Main CLI handler
├── Argument.class.php  # Base argument class
├── Flag.class.php      # Boolean flag arguments
├── Option.class.php    # Value-based options
└── Message.class.php   # Output messaging
CLI Class
description lib/cli/CLI.class.php 
namespace BoomStick\Lib\CLI;

class CLI extends Struct
{
    public function __construct($argc, $argv);
    public function init();
    
    // Add arguments
    public function addFlag(Flag $flag);
    public function addOption(Option $opt);
    
    // Access parsed values
    public function __get($name);
    public function __set($name, $value);
    
    // Output methods
    public function verbose($message, $runAtLevel = 1, $addNewLine = true);
    public function error($message, $addNewLine = true);
    public function prompt($text = null);
    public function NL($count = 1);
    public function TAB($count = 1);
    
    // Help & utilities
    public function getHelp();
    public function getScriptName();
    public function getVerboseLog($delimiter = "\n");
    
    // Colorized output
    public static function colorize($text, $foreground = 'default', $background = null, $effect = null);
    public static function resetColor();
}
Flag & Option Classes
// Flag - Boolean switches (--verbose, -v)
class Flag extends Argument
{
    public $long;        // e.g., 'verbose'
    public $short;       // e.g., 'v'
    public $description; // Help text
}

// Option - Value arguments (--output=file.txt, -o file.txt)
class Option extends Argument
{
    public $long;        // e.g., 'output'
    public $short;       // e.g., 'o'
    public $description; // Help text
    public $required = false;
    public $default = null;
}
Complete CLI Script Example
#!/usr/bin/env php
<?php
require_once 'vendor/autoload.php';

use BoomStick\Lib\CLI\CLI;
use BoomStick\Lib\CLI\Flag;
use BoomStick\Lib\CLI\Option;

$cli = new CLI($argc, $argv);

// Add a flag (boolean)
$dryRun = new Flag();
$dryRun->long = 'dry-run';
$dryRun->short = 'd';
$dryRun->description = 'Run without making changes';
$cli->addFlag($dryRun);

// Add a required option
$inputFile = new Option();
$inputFile->long = 'input';
$inputFile->short = 'i';
$inputFile->description = 'Input file path';
$inputFile->required = true;
$cli->addOption($inputFile);

// Add optional option with default
$outputDir = new Option();
$outputDir->long = 'output-dir';
$outputDir->short = 'o';
$outputDir->description = 'Output directory';
$outputDir->default = './output';
$cli->addOption($outputDir);

// Initialize (parses arguments, shows help if --help)
$cli->init();

// Access values (camelCase from kebab-case)
if ($cli->dryRun) {
    $cli->verbose('Dry run mode enabled', 1);
}

$cli->verbose('Processing: ' . $cli->input, 1);
$cli->verbose('Output to: ' . $cli->outputDir, 1);

// Colorized output
$cli->verbose(CLI::colorize('Success!', 'green'), 0);
$cli->error('Something went wrong'); // Red output to STDERR
Available Colors
Foreground Background Effects
black, red, green, yellow black, red, green, yellow bright, dim
blue, magenta, cyan, white blue, magenta, cyan, white underline, blink, reverse, hidden

storage Database

The database libraries provide PDO-based database connectivity with table, row, and list abstractions.

folder lib/data/db/ 
lib/data/db/
├── Connect.class.php  # Database connection manager
├── Table.class.php    # Table configuration
├── Row.class.php      # Single row operations
└── Lyst.class.php     # List/collection operations
Connect Class
description lib/data/db/Connect.class.php 
namespace BoomStick\Lib\Data\Db;

class Connect
{
    public $pdo;  // PDO instance
    
    public function __construct($dsn, $username, $password);
    
    // Factory methods
    public function initTable();
    public function initLyst($tableConfig = null);
    public function initRow($tableConfig = null);
}
Usage Example
use BoomStick\Lib\Data\Db\Connect;

// Create connection
$db = new Connect(
    'mysql:host=localhost;dbname=myapp',
    'username',
    'password'
);

// Direct PDO access
$stmt = $db->pdo->prepare('SELECT * FROM users WHERE id = ?');
$stmt->execute([123]);
$user = $stmt->fetch();

// Using Row abstraction
$userRow = $db->initRow($usersTableConfig);
$userRow->load(123);
$userRow->name = 'Updated Name';
$userRow->save();

// Using Lyst for collections
$userList = $db->initLyst($usersTableConfig);
$users = $userList->where('active', '=', 1)->fetch();
info PDO Configuration: The Connect class automatically sets ERRMODE_EXCEPTION, FETCH_ASSOC, and UTF-8 encoding.

dns Session Drivers

Session drivers implement different storage backends for the Session class.

folder lib/session/ 
lib/session/
└── LocalPHP.class.php  # PHP native session handler
LocalPHP Driver
description lib/session/LocalPHP.class.php 
namespace BoomStick\Lib\Session;

class LocalPHP
{
    public function __construct($name, $lifetime);
    
    // Session data access
    public function __get($key);
    public function __set($key, $value);
    public function __isset($key);
    public function all();
    
    // Tokens
    public function URLToken();   // Returns: session_name=session_id
    public function CSRFToken();  // Returns: session_id
    
    // Status & persistence
    public function status();     // ACTIVE, NONE, or DISABLED
    public function save();
}
Session Configuration
// In your module's public/index.php:
define('SESSION_ENABLED', true);
define('SESSION_TYPE', 'local');  // Uses LocalPHP driver

// The Session class automatically selects the driver:
// 'local' => BoomStick\Lib\Session\LocalPHP

// Cookie settings configured automatically:
// - HttpOnly: true (prevents XSS access)
// - Path: '/'
// - Domain: extracted from HTTP_HOST
info Extending Sessions: Create custom drivers by implementing the same interface as LocalPHP and adding a case to the Session class switch statement.