Download the PHP package rudra/framework without Composer

Rudra Framework

A lightweight, transparent PHP framework built on the principles of simplicity and clarity.

~15 MB · Lightweight Query Builder · No hidden dependencies · No magic · PHP 8.3 Attributes · Porto Architecture

Philosophy

Rudra follows the KISS principle — every tool is visible, every dependency is explicit, and every layer does exactly one thing. No "magic" happens behind the scenes: if you see it in the code, that's all there is.

• Transparency — no hidden behavior, no implicit side effects
• Simplicity — minimal surface area, easy to learn and extend
• Explicit over implicit — dependencies are declared, not guessed
• Modern PHP — built from the ground up on PHP 8.3+ features (attributes, typed constants, fibers)

Who is this for?

Rudra is built for developers who:

• Prefer explicit code over framework magic — you want to see exactly what SQL is executed, what routes are registered, and what dependencies are injected
• Value cognitive clarity — you need a framework that stays out of your way and doesn't require memorizing hidden conventions
• Work on small-to-medium projects — you want structure and best practices without the overhead of enterprise-grade frameworks
• Want full control — you believe that understanding your tools is more important than having hundreds of features out of the box

If you're looking for a batteries-included framework with built-in ORM, pre-configured queue workers, and ready-made broadcast drivers — Rudra is not for you.
If you want a lightweight, transparent foundation with simple primitives that you can extend exactly as needed — you're in the right place.

Requirements

• PHP 8.3 or higher
• PDO extension
• Composer (for installation)

🚀 Getting started

Via Composer (stable)

Via Composer (dev)

Via Git + DDEV (stable)

Via Git + DDEV (dev)

🔑 Secret Keys

Secret keys are automatically generated during Composer installation for all environments (local, ddev, production). If you need to regenerate them (e.g., after cloning the repository), simply run:

⚙️ Configuration

These files contain database credentials, container paths, debug settings, and other environment-specific values.

🗄️ Database Configuration

Rudra uses a simple, explicit YAML configuration for database connections. There is no hidden magic or auto-guessing: you define exactly which driver and credentials to use for each environment.

Local Development (config/setting.local.yml):

DDEV Environment (config/setting.ddev.yml):

Production (config/setting.production.yml):

💡 Tip: The framework's Query Builder (Rudra-Model) automatically reads these settings based on the active environment. Simply uncomment the dsn line for your preferred database engine (MySQL, PostgreSQL, or SQLite).

🌐 Web Environment (auto-detected)

For web requests, Rudra automatically detects the environment in index.php:

🖥️ Console Environment

For CLI commands (like php rudra migrate), the framework cannot auto-detect the environment as it does in index.php. Instead, it relies on the app_env.php file to determine which configuration file to load (e.g., 'local' → config/setting.local.yml).

🚀 Quick Setup (Recommended)

Use the built-in interactive command to set or change your environment. It will automatically create or update the app_env.php file for you, preserving all comments and structure:

Follow the interactive prompt to select 1 (local), 2 (ddev), or 3 (production).

⚙️ Manual Setup

If you prefer, you can manually create or edit the app_env.php file in your project root:

ℹ️ Note: If app_env.php is missing (e.g., if you cloned the repository directly instead of using composer create-project), the framework defaults to 'local' for CLI commands. This is safe for local development but should not be relied upon in production — always create the file manually or set the APP_ENV server variable explicitly.

💡 Tip: When adding new containers or settings during development, update config/setting.local.yml. For production deployment, copy the relevant sections to config/setting.production.yml.

Run the development server

🚀 Creating Your First Page

Let's create a simple /hello/:name page that greets the user. This example shows the full flow: container → controller → route → browser.

1. Create a container

This creates the App\Containers\Web\ namespace and registers it in config/setting.local.yml.

💡 Don't forget to also register it in config/setting.ddev.yml and config/setting.production.yml if needed.

2. Create a controller

This generates App/Containers/Web/Controller/HelloController.php.

3. Define the route and action

Open the controller and add a method with the #[Routing] attribute:

That's it. The route is registered automatically via the attribute — no separate routes.php needed.

4. Open in browser

You should see: Hello, world! Your lucky number is: 42

Alternative: routes.php

If you prefer to keep routes separate from controllers, create (or edit) App/Containers/Web/routes.php:

⚠️ When using routes.php for manual routing, make sure the file returns an empty array to disable automatic attribute-based route registration:

Alternative: closure route

For quick prototyping, you can even skip the controller entirely:

Then open http://127.0.0.1:8000 in your browser.

📦 Ecosystem Components

Rudra is built on a modular component architecture. Each component is a standalone Composer package — use only what you need, or install everything via rudra/framework.

🔑 Key Features in Action

🔐 Authentication & RBAC

🎧 Event Dispatcher (Listeners + Observers)

✅ Fluent Validation

🧭 RESTful Resources

Registers standard CRUD routes with explicit plural and singular URL patterns. No magic pluralization — you define exactly what the URLs look like.

This creates the following routes:

The default action names are ['index', 'read', 'create', 'update', 'delete'].

Custom Method Names

You can override the default action names by passing a custom array of 5 methods:

The array order is fixed: [index, read, create, update, delete].

🖼️ View with Caching

💾 Data Access Layer (Rudra-Model)

Rudra includes a lightweight, transparent data access layer — not a heavy ORM, but a simple Query Builder with Repository pattern.

Architecture: Entity → Model → Repository

A predictable delegation chain with automatic fallback:

• Entity — entry point, defines the table name
• Model — business logic layer (optional)
• Repository — data access layer (optional, falls back to base CRUD)

If you don't create a Model or Repository, the base Repository handles standard CRUD automatically.

Zero Boilerplate

Custom Repository Logic

Fluent Query Builder

Schema Builder

File-Based Caching

Simple, reliable JSON file caching — no Redis/Memcached required:

Why Not a Heavy ORM?

• No magic — no hidden queries, no lazy loading surprises
• No hidden dependencies — direct PDO access when needed
• Predictable — you see exactly what SQL is executed
• Fast — no reflection overhead, no entity hydration complexity
• Simple — if you know SQL, you know Rudra-Model

🛠️ CLI Tools

Rudra ships with a rich set of CLI utilities following the Porto architecture. Run php rudra help to see the full list.

🚀 Launch & Help

🛠️ Generators (make:*)

🗄️ Database

🔍 Debug

🔐 Security

🧹 Maintenance & Utils

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) — a free, open-source license that:

• ✅ Requires preservation of copyright and license notices
• ✅ Allows commercial and non-commercial use
• ✅ Requires that modifications to original files remain open under MPL-2.0
• ✅ Permits combining with proprietary code in larger works

📄 Full license text: LICENSE
🌐 Official MPL-2.0 page: https://mozilla.org/MPL/2.0/