README

Luminara is a lightweight PHP framework with just enough magic. It is built from scratch utilizing PHP 8.2+ features like strict typing, readonly properties, and modern syntax to provide a blazing-fast, PSR-compliant foundation for your web applications.

Core Philosophy: Prioritize developer happiness, clean syntax, and rapid application development without the bloat.

Official Documentation

Luminara is completely documented. Whether you are a beginner or an advanced developer, you'll find everything you need to know in our detailed documentation files:

Getting Started
Directory Structure
Routing
Controllers
Views & Spark Templating
Database & ORM
Database Migrations
Middleware
Auth & Session
Validation Engine
File Storage
Caching System
Security & Sanitization
Hardened SMTP Mailer
Error Handling & Logging
Service Container (DI)
Spark CLI Tooling

Getting Started

Requirements

PHP 8.2 or higher
Composer
PDO PHP Extension (for database support)

Installation

Create a new Luminara project via Composer:

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

Start the built-in development server:
```
php spark serve
```

Your application will now be running at http://localhost:8000.

Directory Structure

├── app/                  # Your application code
│   ├── Controllers/      # HTTP Controllers
│   ├── Models/           # Database Models
│   └── Middleware/       # Custom HTTP Middleware
├── bootstrap/            # App initialization script
├── config/               # Configuration files (app.php, database.php)
├── database/             # Migrations and SQLite databases
├── public/               # Web root (index.php and assets)
├── resources/
│   └── views/            # Spark template files (.spark.php)
├── routes/               # Route definitions (web.php)
├── src/                  # Core Framework Source Code
├── storage/              # Generated files (app uploads, view cache, logs)
└── spark                 # The CLI executable

Routing

Routes are defined in routes/web.php. The router supports all standard HTTP verbs, dynamic parameters, route naming, and middleware groups.

Basic Routing

use App\Controllers\HomeController;

// Closure route
$router->get('/hello', function () {
    return 'Hello World';
});

// Controller route
$router->get('/', [HomeController::class, 'index'])->name('home');

Route Parameters & Groups

$router->get('/users/{id}', function (string $id) {
    return "User ID: " . $id;
});

$router->group(['prefix' => '/admin', 'middleware' => 'AuthMiddleware'], function ($router) {
    $router->get('/dashboard', [AdminController::class, 'dashboard']);
});

Controllers

Controllers handle your application logic. Generate a new controller using the Spark CLI:

php spark make:controller UserController

Controllers automatically resolve dependencies via the Service Container and provide helper methods like $this->view() and $this->json().

Views & Spark Templating

Luminara features Spark, a lightweight, Blade-inspired templating engine that compiles to plain PHP for maximum performance. Views are stored in resources/views and use the .spark.php extension.

Layouts & Inheritance

resources/views/layouts/app.spark.php:

<!DOCTYPE html>
<html>
<head>
    <title>@yield('title', 'Default Title')</title>
</head>
<body>
    <div class="container">
        @yield('content')
    </div>
</body>
</html>

resources/views/users/index.spark.php:

@extends('layouts.app')

@section('title') User List @endsection

@section('content')
    <h1>Users</h1>
    <ul>
        @foreach($users as $user)
            <li>{{ $user->name }} - {{ $user->email }}</li>
        @endforeach
    </ul>
@endsection

Spark Syntax Guide

Echoing Data: {{ $variable }} (Automatically escaped to prevent XSS)
Raw Data: {!! $variable !!} (Unescaped HTML)
Conditionals: @if($condition) ... @elseif($other) ... @else ... @endif
Loops: @foreach($items as $item) ... @endforeach
Security: @csrf (Generates a hidden CSRF token input)

Database & ORM

Luminara provides a fluent Query Builder and an Eloquent-style Active Record ORM. Configure your database connection in the .env file.

Lazy Connections & XAMPP Integration

Luminara is highly optimized and uses Lazy Database Connections. The framework will not connect to your database unless a route specifically requests data. This allows purely HTML-driven pages to render instantly without database overhead.

If your application requires a database query and XAMPP (MySQL) is not running, Luminara will instantly intercept the fatal connection failure and render a beautiful, glowing warning screen telling you to start XAMPP, rather than failing silently or exposing raw PDO errors.

Active Record Models

Generate a model using the CLI:

php spark make:model Post

namespace App\Models;

use Luminara\Database\Model;

class Post extends Model
{
    protected array $fillable = ['title', 'content', 'user_id'];
    
    public function author(): ?Model
    {
        return $this->belongsTo(User::class, 'user_id');
    }
}

Using Models (CRUD)

// Create
$post = Post::create(['title' => 'Hello', 'content' => '...']);

// Read
$post = Post::find(1);
$activePosts = Post::where('status', 'published')->get();

// Update
$post->title = 'New Title';
$post->save();

// Delete
$post->delete();

Database Migrations

Luminara features a robust, version-controlled database schema builder.

Generate a new migration using Spark:

php spark make:migration create_posts_table

This will create a timestamped file in database/migrations/:

use Luminara\Database\Schema;
use Luminara\Database\Blueprint;

class CreatePostsTable
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
}

To run all pending migrations:

php spark migrate

Middleware

Middleware provides a convenient mechanism for inspecting and filtering HTTP requests entering your application.

Generate a middleware:

php spark make:middleware EnsureTokenIsValid

namespace App\Middleware;

use Closure;
use Luminara\Http\Middleware;
use Luminara\Http\Request;
use Luminara\Http\Response;

class EnsureTokenIsValid implements Middleware
{
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->input('token') !== 'secret') {
            return new Response('Unauthorized', 401);
        }

        return $next($request);
    }
}

Auth & Session

Luminara includes a built-in Authentication and Session management system.

To quickly scaffold a fully working login and registration system (Controllers, Views, and Routes), run:

php spark make:auth

Using Auth Helpers

You can easily interact with the authenticated user anywhere in your app:

// Attempt to log a user in securely
if (auth()->attempt(['email' => $email, 'password' => $password])) {
    return redirect('/dashboard');
}

// Check if a user is logged in
if (auth()->check()) {
    $user = auth()->user();
    echo "Welcome, " . $user->name;
}

// Log out
auth()->logout();

Validation Engine

Validating incoming HTTP requests is incredibly simple. Call the validate() method directly on the $request object.

$router->post('/submit', function(Request $request) {
    // If validation fails, it automatically redirects back!
    $validated = $request->validate([
        'name'     => 'required|string|max:50',
        'email'    => 'required|email',
        'password' => 'required|min:8'
    ]);
    
    User::create($validated);
});

Showing Validation Errors in Views

When validation fails, Luminara automatically flashes the errors and old input to the session. You can easily retrieve them in your .spark.php views:

<input type="text" name="email" value="{{ old('email') }}">

@if(errors('email'))
    <span style="color: red;">{{ errors('email') }}</span>
@endif

File Storage

Luminara provides a powerful filesystem abstraction that automatically scopes your file interactions to the storage/app/ directory for security.

Managing Files

// Write to storage/app/reports/data.txt
storage()->put('reports/data.txt', 'Content here');

// Read contents
$content = storage()->get('reports/data.txt');

// Delete a file
storage()->delete('reports/data.txt');

File Uploads

Storing an uploaded file directly from the HTTP Request is trivial:

$file = $request->file('avatar'); // gets $_FILES['avatar']

if ($file) {
    // Moves to storage/app/avatars/profile.png
    storage()->putFileAs('avatars', $file, 'profile.png');
}

Caching System

Luminara features a unified caching layer that enables quick data storage and retrieval using key-value adapters:

Drivers: Supports both filesystem-based storage (FileDriver) and Redis-backed cache storage (RedisDriver), configured in the .env settings.
Cache Helper: Easy read, write, and delete operations via the global cache() helper:

// Retrieve a value from the cache
$value = cache('user_data');

// Store a value for 600 seconds
cache('user_data', $user, 600);

// Interact directly with the CacheManager
$cacheManager = cache();

Security & Sanitization

Security is built into Luminara's core middleware pipeline:

Input Sanitization: The custom InputSanitizer middleware automatically processes request variables ($_GET and $_POST) recursively to filter harmful HTML and script tags, protecting against Cross-Site Scripting (XSS).
CSRF Protection: Safe requests are guarded with session-matched token checkpoints. Use the @csrf template helper to embed the input element automatically.

Hardened SMTP Mailer

Luminara implements a professional email processing suite under the Mailer/ directory:

SmtpMailer: Handles direct SMTP socket connections, security handshakes, and body transmission.
MailDkim: Cryptographically signs outbound email headers using RFC 6376 DKIM protocols to authenticate domain headers and maximize inbox deliverability.
MailBounce: A background POP3/IMAP daemon that intercepts delivery reports and filters bounced addresses.
MailGuard & MailPreflight: Validates receiver compliance, prevents rapid rate abuse, and handles checks before starting delivery.
MailQueue / worker.php: Enables asynchronous spooling to run mail delivery in background worker processes.
MailPreview & MailStats: Visualizes email formatting and displays deliverability metrics and delivery logs.

Error Handling & Logging

Ignition-Style Debug Screen

When your application throws an exception and APP_DEBUG=true is set in your .env file, Luminara will intercept the error and render a beautiful, detailed debug screen displaying the exact file, line number, code snippet, and stack trace. In production (APP_DEBUG=false), it gracefully falls back to a clean 500 error page.

Logging

You can log messages anytime using the global logger() or info() helpers. Logs are automatically appended to storage/logs/luminara.log.

info('User logged in!', ['user_id' => 5]);
logger()->error('Failed to connect to API.');

Service Container (DI)

At the heart of Luminara is a powerful PSR-11 Inversion of Control (IoC) Container. It handles auto-wiring of dependencies for Controllers, Middleware, and internal framework services.

// Resolving from the container (or use constructor injection!)
$cache = app(CacheService::class);

Spark CLI Tooling

Luminara comes with Spark, a built-in command-line interface to automate scaffolding, compilation, monitoring, and database management.

Commands Reference

# Server & Monitoring
php spark serve                      # Start the built-in development server
php spark monitor:traffic            # Monitor HTTP request traffic in real-time

# Scaffolding Boilerplate
php spark make:controller UserController   # Create controller and matching model
php spark make:model Post                  # Create an Eloquent-style Active Record model
php spark make:middleware AuthMiddleware  # Create custom HTTP middleware
php spark make:migration create_posts      # Create a version-controlled database schema migration
php spark make:auth                  # Scaffold complete login/register routes and views
php spark make:library-system        # Scaffold a fully functional library management module

# Database Schema
php spark migrate                    # Run all pending migrations

# Route Compilation
php spark route:list                 # List all registered routing definitions
php spark route:cache                # Cache route definitions for production
php spark route:clear                # Remove the compiled route cache

# View Compilation
php spark view:cache                 # Precompile all templates for maximum speed
php spark view:clear                 # Clear the compiled template cache files

License

The Luminara framework is open-sourced software licensed under the MIT license.

luminara / luminara

Maintainers

Package info

Statistics

Security