Utilities

In mouse-php, Utilities are single-purpose, reusable helper classes designed to handle cross-cutting system tasks, such as database query wrapping, environment variable parsing, and SQLite log streaming.

Rather than pulling in heavy third-party vendor dependencies for simple operations, mouse-php provides a suite of hyper-optimized core utilities out of the box.

Developers are also encouraged to create Custom Utilities for any logic that needs to be shared across multiple Controllers, Models, or Middleware modules, adhering strictly to the DRY (Don't Repeat Yourself) principle without adding framework bloat.

Architectural Philosophy: The Utility Rule

The core guideline for code organization in mouse-php is simple:

The Utility Rule: If a piece of logic (string formatting, token generation, encryption, external API calling) is used, or could be used, in more than one place, it should be extracted into a standalone Utility class in ./core/utils/.

This keeps Controllers thin, Models focused purely on query pipelines, and Middleware focused strictly on request guarding.

Built-In Core Utilities

A. Database Wrapper (Database_Handler.php)

The Database_Handler utility acts as a lightweight wrapper over PHP’s native PDO driver. It enforces prepared statement parameter binding via explicit tuples while eliminating PDO boilerplate.

Method Signature

$db->make_query(string $action, string $query, array $vals = []);

• $action: Query type identifier ("select", "insert", "update", "delete").
• $query: Raw SQL statement containing named parameters (e.g., :email).
• $vals: Array of parameter binding arrays.

Parameter Binding Format

Each parameter in $vals is an associative array defining the name, value, and data type:

Type Flag	Data Type	PHP Native Mapping
"i"	Integer	PDO::PARAM_INT
"s"	String	PDO::PARAM_STR
"b"	Boolean	PDO::PARAM_BOOL
"l"	Blob	PDO::PARAM_LOB

Query Example

$query = "INSERT INTO users (username, email, age) VALUES (:user, :email, :age)";

$vals = [
    ["name" => ":user",  "value" => "johndoe",          "type" => "s"],
    ["name" => ":email", "value" => "john@example.com", "type" => "s"],
    ["name" => ":age",   "value" => 29,                 "type" => "i"]
];

$inserted_id = $db->make_query("INSERT", $query, $vals);

Dual Connection Support: mouse-php injects both $DB (Primary SQL connection, e.g., PostgreSQL/MySQL) and $SQLITE (Local SQLite connection) into controllers and middleware, allowing you to use local SQLite databases for fast caching, rate limiting, or session storage alongside your primary data store.

B. Environment Loader (Env_Bootstrap.php)

mouse-php includes vlucas/phpdotenv out of the box, the single Composer dependency shipped with the core framework.

During core bootstrapping, the Env_Bootstrap utility initializes Dotenv to load environment configuration from ./core/{type}.env into PHP's global environment space based on the current execution context.

• Location: Reads configuration files inside ./core/ (e.g., ./core/app.env or ./core/db.env).

Usage:

// Access environment variables cleanly anywhere in the app
$env = new \utils\Env_Bootstrap("app"); // Loads app config by default
$address  = $env->get_var("ADDRESS");
$protocol = $env->get_var("PROTOCOL");

C. File & Event Logger (Log_Handler.php)

The Log_Handler utility provides lightweight, structured event logging for error tracking, request auditing, and system debugging.

• Log Storage: Writes structured log entries directly into mouse.db via the $SQLITE connection handle. This database-backed logging allows the squeak CLI tool to perform real-time auto-tailing and log filtering during development.
• Signature: The log() method accepts an event type string, a log message, and an optional user ID parameter.

Usage Example

$logger = new \utils\Log_Handler($sqlite);

// Log an system event with optional user association
$logger->log("AUTH_FAILURE", "Invalid token provided", $user_id);

The Composer & Dependency Philosophy

mouse-php is built on a principle of zero forced bloat.

While monolithic frameworks force dozens of transitive vendor packages onto your project before you write a single line of code, mouse-php ships with a clean slate.

• Default State: Hyper-lean execution. Everything outside of environment parsing is handled by lightweight, native PHP utilities.
• Developer Choice: If your application requires external SDKs (such as Stripe, AWS, Redis clients, or Guzzle), you can add them freely via Composer (composer require vendor/package).

Composer support is entirely downstream: you decide what enters your dependency tree, not the framework.

Creating Custom Utilities

When building applications, you will often need shared logic for tasks like JWT token verification, password hashing, payment gateway integration, or third-party API communication.

Scaffolding via Squeak CLI (Recommended)

We recommend using squeak to generate new utility classes automatically by using the add-utility command inside the squeak shell.

Creating Utilities Manually

If you prefer to create a utility manually:

1. Place your class file in ./core/utils/.
2. Assign the class to the namespace utils; namespace.
3. Keep methods stateless where possible so they can be invoked cleanly across the application.

Example: Custom Token Helper Utility

// File: ./core/utils/Token_Helper.php
namespace utils;

class Token_Helper {
    /**
    * Generates a cryptographically secure random token string.
    */
    public function generate_random_token($length = 32) {
        return bin2hex(random_bytes($length));
    }

    /**
     * Sanitizes strings for safe URL usage.
     */
    public function sanitize_slug($input) {
        return strtolower(trim(preg_replace('/[^A-Za-z0-9-]+/', '-', $input)));
    }
}

Accessing Custom Utilities in Controllers or Middleware

Because mouse-php uses standard namespace autoloading, you can instantiate and call custom utilities anywhere in your codebase:

namespace controllers;

class Auth_Controller {
    public function generate_api_key() {
        $token_gen = new \utils\Token_Helper();
        $new_key   = $token_gen->generate_random_token(16);

        echo json_encode([
            "status"  => true, 
            "api_key" => $new_key
        ]);
    }
}