README

Strux is a modern, lightweight, and powerful PHP framework designed for building robust web applications and APIs. It combines a clean architecture with a rich feature set—including an Active Record ORM, built-in queue system, event dispatcher, and flexible middleware—while maintaining a minimal core with few external dependencies.

Strux strictly adheres to PSR-1, PSR-2, PSR-3, PSR-4, and PSR-7 standards for maximum interoperability.

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Directory Structure
• Routing
• Controllers
• Requests & Responses
• Middleware
• Views & Templating
• Database & ORM
• Migrations
• Query Builder
• Model Relationships
• Event Dispatcher
• Queue System
• Security
• Command-Line Interface (CLI)
• License

✨ Features

• PSR-compliant architecture (PSR-1, 2, 3, 4, 7)
• Zero external dependencies
• Attribute-based routing and ORM
• Active Record ORM with relationships
• Middleware dispatcher
• Event & queue systems
• Built-in validation and security
• CLI tooling for rapid development
• Plates templating (Twig adapter available)

🧰 Requirements

• PHP 8.2+
• Composer
• PDO extension (for database access)

🚀 Installation

Create a New Project

composer create-project strux/strux-app my-app
cd my-app

Serve the Application

php bin/console run

⚙️ Configuration

Configuration files are stored in the etc/ directory and are automatically loaded.

Environment Variables

Copy the example environment file and update it:

cp .env.example .env

APP_ENV=local
APP_DEBUG=true

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=strux_db
DB_USERNAME=root
DB_PASSWORD=secret

📂 Directory Structure

bin/        # CLI entry point
etc/        # Configuration & route files
src/        # Application source code
templates/  # Views, assets, language files
web/        # Public entry point (index.php)
var/        # Cache, logs, sessions

🛣 Routing

Routes are defined in etc/routes/web.php or etc/routes/api.php.

Fluent Routing

$router->get('/', [HomeController::class, 'index']);
$router->get('/users/:id', [UserController::class, 'show']);
$router->post('/login', [AuthController::class, 'login'])->name('login');

Attribute-Based Routing

use Strux\Component\Attributes\Route;

class UserController
{
    #[Route('/users/:id', methods: ['GET'])]
    public function show(int $id) {}
}

🎮 Controllers

Controllers live in src/Http/Controller and receive dependencies automatically via the service container.

class PageController extends Controller
{
    public function home(Request $request)
    {
        return $this->view('home', ['name' => 'Strux']);
    }
}

📥 Requests & Responses

Request Access

$request->input('name');
$request->safe()->input('name'); // Sanitized
$request->query('page');
$request->header('User-Agent');
$request->file('avatar');

Responses

return $this->view('profile');
return $this->json(['status' => 'ok']);
return $this->redirect('/login');

🛡 Middleware

Middleware intercepts requests before controllers execute.

class AuthMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request, 
        RequestHandlerInterface $handler): ResponseInterface
    {
        if (!Auth::check()) {
            return $this->responseFactory->createResponse(302)
            ->withHeader('Location', '/login');
        }
        return $handler->handle($request);
    }
}

• Global middleware: etc/middleware.php
• Route-specific or attribute-based registration supported

🎨 Views & Templating

Strux uses Plates by default (Twig supported via adapter).

return $this->view('auth/login', ['error' => 'Invalid credentials']);

<?php $this->layout('layouts/app', ['title' => 'Login']) ?>
<h1>Login</h1>

🗄 Database & ORM

Strux includes an Active Record ORM using PHP Attributes.

Model Definition

#[Table('users')]
class User extends Model
{
    #[Id]
    #[Column('id')]
    public int $id;

    #[Column('username')]
    public string $username;
}

Basic Usage

$user = new User();
$user->username = 'john_doe';
$user->save();

$user = User::find(1);
$user->delete();

🏗 Migrations

php bin/console db:migrate

🔍 Query Builder

$users = User::query()
    ->where('active', 1)
    ->where('age', '>', 18)
    ->orderBy('created_at', 'DESC')
    ->limit(10)
    ->get();

🔗 Model Relationships

Supported relationships:

• #[HasOne]
• #[HasMany]
• #[BelongsTo]
• #[BelongsToMany]

#[BelongsToMany(related: Course::class, pivotTable: 'enrollments')]
public Collection $courses;

$student->courses;
$student->courses()->sync([1, 2, 3]);

📡 Event Dispatcher

Event::dispatch(new UserRegistered($user));

class SendWelcomeEmail
{
    public function handle(UserRegistered $event) {}
}

📨 Queue System

Queue::push(new SendEmailJob($user));
php bin/console queue:start

🔒 Security

• Authentication via Sentinels (Session, JWT)
• Authorization with #[Authorize] attributes
• CSRF protection middleware
• Built-in validation system (Required, Email, MinLength, etc.)

💻 Command-Line Interface (CLI)

php bin/console
php bin/console new:controller
php bin/console new:model
php bin/console db:seed

📄 License

Strux Framework is open-source software licensed under the MIT License.