README

  Veloce Framework

Veloce is a lightweight and high-performance PHP framework (PHP 8.2+) built on the principles of strict typing, data immutability, and ahead-of-time resource compilation.

  Standards

• PHP 8.2+: Code uses modern features (readonly, types).
• Strict Types: Each file begins with declare (declare(strict_types=1);).
• English Only: Technical English for all documentation and PHPDoc.

  Key Features

• Ultra-fast Routing: Routes are pre-compiled into optimized PHP maps. Zero regex parsing overhead during the request lifecycle.
• Smart DI-Container: Full Auto-wiring support via Reflection API. Effortless dependency management with interface-to-implementation binding.
• Hybrid Security: Native CSRF protection (supporting Forms & JSON payloads), AES-128-CBC encryption, and automated XSS defense.
• Data Integrity: Leveraging PHP readonly properties for Request and Path objects to ensure data remains unchanged.
• Lazy Rendering: Isolated template execution using Sandboxed Closures. Templates are rendered only when the response is ready to be sent.

  Security First

• Hybrid CSRF Protection: Native validation for both classic HTML form-data and modern JSON-based API requests.
• Industry-Standard Encryption: AES-128-CBC + HMAC (Encrypt-then-MAC) for session-sensitive data.
• Automated XSS Defense: Integrated escape() utility and secure Input object with built-in sanitization.

  Quick Start

1. Installation

Get the package via Composer:

composer require oslinia/veloce

1. Initialize Infrastructure

Setup required directories and security configurations:

php bin/console

1. Define Routes

Add your first rule in application/rules.php:

use Veloce\Routing\Rule;

Rule::route('/user/{id}', 'user.profile', UserController::class)
    ->where(id: '\d+');

1. Create a Controller

Implement your logic in application/Controller/UserController.php:

namespace Application\Controller;

use Veloce\Kernel\Controller;
use Veloce\Kernel\Path;

class UserController extends Controller {
    public function profile(Path $path): array {
        return $this->render_template('user/profile.php', [
            'id' => $path->int('id')
        ]);
    }
}

  CLI Build Tool

The built-in binary utility manages the storage/ infrastructure:

• php bin/console — Initialize: Setup directories and default settings in storage/.
• php bin/console reload — Recompile: Refreshes routing maps in storage/routing/.
• php bin/console salt — Security: Rotates the storage/salt.php (invalidates current tokens).

  Dependency Injection

Veloce resolves dependencies recursively. Just hint the class in your constructor:

namespace Application\Controller;

use Veloce\Kernel\Controller;
use Veloce\Kernel\Logger;

class ApiController extends Controller {
    public function __construct(
        private Logger $logger // Automatically injected by Veloce Container
    ) {}

    public function index(): array {
        $this->logger->log("API accessed");
        return parent::base_response("OK");
    }
}

  Core Architecture

Compiled Routing

Veloce shifts the heavy lifting from Runtime to Build-time. The Reload service transforms human-readable route definitions into high-performance PHP arrays, which are cached and loaded via Opcache.

Isolated View Scope

Templates are rendered within an anonymous function scope. This prevents variable leakage and allows for "Lazy Rendering" — the HTML is generated only at the very end of the request-response cycle.

Cryptography

We use an Encrypt-then-MAC approach for session-sensitive data.

• AES-128-CBC for confidentiality.
• SHA-256 HMAC for integrity verification.

  Project Structure

• application/ — Your controllers and business logic (Application\Controller).
• bin/ — CLI Build tools (php bin/console).
• logs/ — System and error logs (Daily rotation).
• public/ — Web entry point (index.php) and static assets.
• storage/ — Generated assets: Compiled routing, security salt, and environment settings.
• src/ — Core framework engine (Veloce\).

  License

The Veloce Framework is open-source software licensed under the MIT license.

Built for speed. Designed for safety.