README

A modern, full-stack PHP 8.5+ framework for building scalable, real-time web applications with unified frontend rendering.

📋 Table of Contents

Why VeloxPHP?
Quick Start
Code Examples
Key Features
Tech Stack & Requirements
Project Templates
Architecture
ForgeORM
Roadmap
Contributing
Versioning
License
Credits

Why VeloxPHP?

VeloxPHP stands out with its unique approach to modern web development:

✨ One respond() method, infinite frontends — Write your controller logic once, render to Twig, React, Vue, or JSON automatically based on APP_FRONTEND configuration. Perfect for component-driven UIs or server-rendered applications.

🗄️ ForgeORM: The ORM that bridges databases — Native support for MySQL 8, PostgreSQL 16, SQLite, and MongoDB 7 with cross-driver SQL↔NoSQL relations, lazy loading, 14 event Attributes, and code-first schema generation. Use as a standalone package in any PHP project.

⚡ Native WebSockets via FrankenPHP — Real-time bidirectional communication without external services (no Reverb, no Soketi). Public/private/presence channels decorated with Attributes. TypeScript bridge, React hooks, and Vue composables built-in.

📊 Auto-generated GraphQL — Queries, mutations, and subscriptions automatically generated from ForgeORM entities. DataLoader/BatchLoader built-in to prevent N+1 queries. GraphQL playground included.

🔍 API Explorer — Interactive React UI at /_velox/explorer with auto-generated forms from FormRequests, request collections, visual assertions, and exportable test scenarios in Pest syntax.

🔐 2FA & Email Verification — RFC 6238 TOTP implementation, inline SVG QR codes, backup codes, trusted device tracking. Email verification via 6-digit codes with rate limiting.

🏢 Multi-Tenant Ready — Four resolution strategies (subdomain, path, header, JWT claim), shared or isolated databases, automatic TenantScope for ForgeORM relations, and CLI commands for tenant management.

🌍 Universal i18n — Single t() function across PHP, Twig, React, and Vue. CLI utilities to find missing translations, detect unused keys, and manage JSON exports/imports.

Quick Start

Installation

composer create-project veloxphp/velox my-app
cd my-app

# Copy environment template
cp .env.example .env

# Generate application key
php velox key:generate

# Create database
php velox make:database

# Serve the application
php velox serve

Your application is now running at http://localhost:8000.

Code Examples

Cross-Frontend Controller

Write once, render anywhere:

<?php

declare(strict_types=1);

namespace App\Controllers;

use App\Entities\Post;
use App\Requests\CreatePostRequest;
use VeloxPHP\Controller\BaseController;

#[Route('GET', '/posts')]
class PostController extends BaseController
{
    #[Route('GET', '/posts/{id}')]
    public function show(int $id)
    {
        $post = Post::find($id) ?? abort(404);
        
        return $this->respond('posts.show', [
            'post' => $post,
            'author' => $post->author,  // Lazy-loaded relation
        ]);
    }

    #[Route('POST', '/posts')]
    public function store(CreatePostRequest $request)
    {
        $post = Post::create($request->validated());
        
        return $this->redirect("/posts/{$post->id}");
    }
}

Automatic rendering based on APP_FRONTEND:

react → Sends JSON, renders React component at resources/js/pages/posts/Show.tsx
vue → Sends JSON, renders Vue component at resources/js/pages/posts/Show.vue
twig → Renders resources/views/posts/show.html.twig server-side
api → Always returns JSON

ForgeORM Entity with Cross-Driver Relation

<?php

declare(strict_types=1);

namespace App\Entities;

use ForgeORM\Attributes\{Entity, Id, Column, HasMany, BelongsTo, MongoId};

#[Entity(table: 'posts')]
class Post
{
    #[Id]
    #[Column]
    public int $id;

    #[Column]
    public string $title;

    #[Column]
    public string $body;

    #[Column]
    public int $author_id;

    #[BelongsTo(User::class)]
    public User $author;

    // Cross-driver relation: MongoDB comments on SQL post
    #[HasMany(Comment::class, 'post_id')]
    public array $comments = [];

    #[Column(name: 'created_at')]
    public string $createdAt;
}

Native WebSocket Channel

Declare channels with Attributes, authorize with closures:

<?php

declare(strict_types=1);

namespace App\Channels;

use VeloxPHP\WebSocket\Attributes\Channel;
use VeloxPHP\WebSocket\PresenceChannel;

#[Channel('chat.{roomId}')]
class ChatChannel extends PresenceChannel
{
    public function authorize(User $user, int $roomId): bool
    {
        return $user->hasAccessToRoom($roomId);
    }

    public function getMembers(): array
    {
        return $this->connections()->map(fn ($conn) => [
            'id' => $conn->user_id,
            'name' => $conn->user->name,
        ])->all();
    }
}

Use in React:

import { useChannel } from '@veloxphp/react';

export default function ChatRoom({ roomId }) {
    const channel = useChannel(`chat.${roomId}`);

    useEffect(() => {
        channel.on('MessageSent', (data) => {
            setMessages(prev => [...prev, data.message]);
        });
    }, [channel]);

    return <div>{/* UI */}</div>;
}

Auto-Generated GraphQL

ForgeORM entities automatically expose GraphQL types:

query GetPost($id: ID!) {
    post(id: $id) {
        id
        title
        body
        author {
            id
            name
            email
        }
    }
}

mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        post {
            id
            title
        }
        message
    }
}

subscription OnCommentCreated($postId: ID!) {
    commentCreated(postId: $postId) {
        id
        body
        author { name }
    }
}

GraphQL playground at /_velox/graphql.

Key Features

Validation & Form Requests

Framework-level validation with automatic error formatting:

#[Route('POST', '/users')]
public function store(CreateUserRequest $request)
{
    // Validation runs automatically, returns 422 if invalid
    $validated = $request->validated();
    
    return User::create($validated);
}

class CreateUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email'    => Rule::email()->required()->unique('users'),
            'password' => Rule::string()->required()->min(8),
            'name'     => Rule::string()->required()->max(255),
        ];
    }

    public function authorize(): bool
    {
        return true;
    }
}

Storage Multi-Drivers

Unified interface for local, S3, and SFTP:

use VeloxPHP\Storage\StorageManager;

$disk = StorageManager::disk('s3');

// Upload
$file->store('avatars', ['disk' => 's3']);

// Generate temporary URLs
$url = $disk->temporaryUrl('avatars/user-1.jpg', minutes: 60);

// Delete
$disk->delete('avatars/user-1.jpg');

Debug Plugin

Structurally disabled in production. Rainbow-colored terminal output in development:

# Enable debug bar in frontend
$ DEBUG_BAR_ENABLED=true php velox serve

# Real-time log tail
$ php velox log:tail --level=error

Middleware Pipeline

PSR-15 compatible middleware stack:

#[Route('POST', '/api/users')]
#[Middleware(CsrfMiddleware::class)]
#[Middleware(AuthMiddleware::class)]
#[Middleware(ThrottleMiddleware::class, '60,1')]  // 60 requests per minute
public function store(CreateUserRequest $request) { }

Tech Stack & Requirements

Minimum Requirements:

PHP 8.5+
Composer
Node.js 18+ (for frontend tooling)

Supported Databases:

MySQL 8.0+
PostgreSQL 16+
SQLite 3.35+
MongoDB 7.0+

Frontend Adapters:

Twig 3.0+ (server-side templates)
React 18+ (via Vite)
Vue 3+ (via Vite)
JSON API

Production:

FrankenPHP (built-in WebSocket workers)
Nginx or Apache with PHP-FPM
Redis (optional cache/session driver)

Minimal Dependencies:

forgeorm/forgeorm — ORM engine
twig/twig — Template engine
symfony/console — CLI foundation
PSR interfaces (HTTP, Container, Logging)

Project Templates

Start from a pre-configured skeleton:

# Interactive project setup
velox new my-project

# ✓ Which SQL driver? [mysql/postgres/sqlite]
# ✓ Add MongoDB? [y/N]
# ✓ Frontend adapter? [react/vue/twig/api]
# ✓ Include WebSockets? [y/N]

Available Templates:

API — JSON-only, database-driven, 0 frontend code
SPA React — Vite + TypeScript, component-based
SPA Vue — Vite + TypeScript, Composition API
Server-Rendered — Twig templates, HTMX-ready
SaaS Multi-Tenant — Tenant resolution, isolated databases
Real-Time Messaging — WebSocket channels, presence

Architecture

VeloxPHP follows a clean, layered architecture:

HTTP Request
    │
    ├─→ Bootstrap (load config, DI container, modules)
    │
    ├─→ Kernel (HTTP entry point)
    │
    ├─→ Router (match route, resolve controller)
    │
    ├─→ Middleware Stack (CSRF, Auth, Throttle, CORS)
    │
    ├─→ Controller (user code, business logic)
    │
    ├─→ Validation (automatic FormRequest validation)
    │
    ├─→ Renderer (Twig/React/Vue/JSON)
    │
    └─→ Response (PSR-7)

Opt-in Strict Mode: Undeclared modules are never loaded. Configure exactly what you need in config/app.php:

'modules' => [
    VeloxPHP\Routing\RoutingServiceProvider::class,
    VeloxPHP\Auth\AuthServiceProvider::class,
    VeloxPHP\Cache\CacheServiceProvider::class,
],

ForgeORM

ForgeORM is a separate, standalone package that VeloxPHP depends on. Use it in any PHP project:

composer require forgeorm/forgeorm

Key ORM Features:

Unified QueryBuilder across all drivers
Lazy Loading via proxy classes (no N+1 queries)
Relationship Attributes — #[HasMany], #[BelongsTo], #[BelongsToMany]
Event Attributes — #[BeforeCreate], #[AfterSave], etc. (14 hooks)
Code-First Migrations — Generate SQL from entities
Cross-Driver Relations — SQL tables can have MongoDB relations and vice versa
Batch Loading — DataLoader pattern built-in

Repository: github.com/Justclara42/ForgeORM

Roadmap

VeloxPHP is actively developed with a 9-milestone roadmap:

Milestone	Status	Focus
1-6	✅ Complete	Skeleton, ORM, Auth, Storage, WebSockets, Debug
7	✅ Complete	GraphQL, API Explorer, i18n, Tests, Multi-Tenant
8	🔄 In Progress	Production hardening, docs, CI/CD templates
9	⏳ Planned	Documentation website, community contributions, release v1.0.0

Current Version: v1.0.0-alpha.1 (Changelog)

Contributing

We welcome contributions! VeloxPHP is built for enthusiasts who want to shape a modern PHP framework.

Getting Started

Fork & clone the repository
Branch: git checkout -b feature/my-feature (or fix/my-fix)
Setup: composer install && npm install
Docker: docker compose up -d (MySQL, PostgreSQL, MongoDB, Redis)
Tests: ./vendor/bin/pest

Code Standards

PHP 8.5 syntax with declare(strict_types=1)
PHPStan level 9 — strict static analysis
Pint PSR-12 — code formatting
Pest tests — 100% coverage required for new features
Attributes — prefer PHP 8.5 attributes over YAML/XML

Contribution Types

🐛 Bug fixes → PR to develop
✨ Features → PR to develop (with failing test first)
🔒 Security → Email security@veloxphp.dev
📖 Docs → Edit README.md or create discussion

Pull Request Checklist

Tests pass: ./vendor/bin/pest
Code style: ./vendor/bin/pint
Static analysis: ./vendor/bin/phpstan analyse --level=9
CHANGELOG updated
Commit messages follow Conventional Commits

Versioning

VeloxPHP follows Semantic Versioning 2.0.0 with coordinated cycles:

v1.0.0
 │││└─ PATCH (bug fixes, security)
 ││└── MINOR (new features, retrocompatible)
 │└─── MAJOR (breaking changes)
 └──── Format: vMAJOR.MINOR.PATCH[-prerelease]

Version Lifecycle (24 months per MAJOR)

Phase	Duration	Support
Active	18 months	Features + Security patches
Security Only	6 months	Security patches only
EOL	—	No support

Pre-Release Phases

Before any MAJOR release:

v1.0.0-alpha.1 (API unstable, core team only)
v1.0.0-beta.1 (features complete, RC testing)
v1.0.0-rc.1 (API frozen, production-ready)
v1.0.0 (stable release)

License

VeloxPHP is open-source software licensed under the MIT License — see LICENSE file.

Credits

Creator: Clara Holderbaum

Repository: github.com/Justclara42/VeloxPHP

Community: We thank everyone who contributes, reports bugs, and helps shape VeloxPHP.

Next Steps

Made with ❤️ by the VeloxPHP team | Report Issues • Suggest Features

veloxphp / velox

Maintainers

Package info

Statistics

Security