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

Installation

Get the package via Composer:

composer require oslinia/veloce

Initialize Infrastructure

Setup required directories and security configurations:

php bin/console

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+');

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.

oslinia / veloce

Maintainers

Package info

Statistics

Security