🚀 Muta Framework

A lightweight, secure, and modern PHP MVC Framework built from scratch.
Designed for learning, rapid prototyping, and small-to-medium web applications.

---

📋 Table of Contents

• About
• Features
• Architecture Overview
• Directory Structure
• Requirements
• Installation
• Configuration
• Routing
• Controllers
• Models & Database
• Views & Templating
• Middleware
• Dependency Injection Container
• Validation
• Security
• CLI Commands
• Database Migrations
• Authentication Scaffold
• Error Handling
• Request Lifecycle
• Contributing
• License

---

📖 About

Muta is a handcrafted PHP MVC framework focused on simplicity, security, and clean architecture.

It implements core software engineering patterns including:

• Front Controller
• MVC Architecture
• Middleware Pipeline
• Dependency Injection
• Repository Pattern

The goal of Muta is to help developers understand how frameworks work internally while still providing a solid base for building real-world applications.

---

✨ Features

Category	Features
Architecture	MVC Pattern, Front Controller, Dependency Injection Container
Routing	Dynamic & static routes, route parameters, HTTP method support
Middleware	Composable middleware pipeline
Security	CSRF protection, XSS sanitization, rate limiting, prepared statements
Database	PDO based ORM, Schema builder, migrations
Validation	Server-side form validation with custom rules
Templating	Layout based template engine (.muta.php)
CLI	Artisan-like CLI scaffolding tools
Authentication	One-command login/signup scaffold
Error Handling	Environment aware error handling
Environment	.env configuration support

---

🏗 Architecture Overview

Client Request
      │
      ▼
.htaccess
      │
      ▼
Front Controller (public/index.php)
      │
      ▼
Bootstrap (autoload, env, config)
      │
      ▼
Router
      │
      ▼
Middleware Pipeline
      │
      ▼
Controller
      │
      ▼
Model
      │
      ▼
View Rendering
      │
      ▼
HTTP Response

Design Patterns Used

• Front Controller — Single application entry point
• MVC — Separation of concerns
• Dependency Injection — Automatic dependency resolution
• Middleware Pipeline — Request filtering
• Repository Pattern — Clean database access abstraction
• Template Views — Layout based rendering

---

📁 Directory Structure

muta/
│
├── config/
│   ├── routes.php
│   ├── services.php
│   └── middleware.php
│
├── database/
│   └── migrations/
│
├── public/
│   ├── index.php
│   └── .htaccess
│
├── src/
│   ├── App/
│   │   ├── Controllers/
│   │   ├── Middleware/
│   │   └── Models/
│   │
│   └── Framework/
│       ├── Router.php
│       ├── Request.php
│       ├── Response.php
│       ├── Container.php
│       ├── Validator.php
│       └── Model.php
│
├── views/
│
├── stubs/
│
├── muta.php
├── composer.json
└── .env

---

📦 Requirements

• PHP >= 8.0
• Composer
• Apache or Nginx
• MySQL / MariaDB

---

🛠 Installation

Clone the Repository

git clone https://github.com/yourusername/muta.git
cd muta

Install Dependencies

composer install

Configure Environment

cp .env.example .env

Example .env

DB_HOST=localhost
DB_NAME=muta_db
DB_USER=root
DB_PASS=

APP_ENV=development
APP_DEBUG=true

Run Migrations

php muta.php migrate

---

🛤 Routing

$router->add('/', [
  'controller' => Home::class,
  'action' => 'index'
]);

$router->add('/products/{id}', [
  'controller' => Products::class,
  'action' => 'show'
]);

$router->add('/products', [
  'controller' => Products::class,
  'action' => 'store',
  'method' => 'POST'
]);

---

🎮 Controllers

Create controller

php muta.php make:controller ProductController

Example:

class Products extends Controller
{
    public function index(Request $request): Response
    {
        $products = $this->product->findAll();

        return $this->view('Products/index.muta.php', [
            'products' => $products
        ]);
    }
}

---

🗄 Models & Database

Create model

php muta.php make:model Product

Example model:

class Product extends Model
{
    protected string $table = 'products';
}

Built-in CRUD methods:

• find()
• findAll()
• create()
• update()
• delete()

---

🎨 Views & Templating

Two view types:

1. Layout Views (.muta.php)

views/Products/show.muta.php

2. Standalone Views (.php)

Used for emails, error pages, etc.

---

🔗 Middleware

Create middleware:

php muta.php make:middleware AuthenticateMiddleware

Middleware example:

public function process(Request $request, RequestHandlerInterface $handler): Response
{
    if (!isset($_SESSION['user_id'])) {
        return new Response(302, '', ['Location' => '/login']);
    }

    return $handler->handle($request);
}

---

📦 Dependency Injection Container

Register services:

$container->set(Database::class, function () {
    return new Database(
        $_ENV['DB_HOST'],
        $_ENV['DB_NAME'],
        $_ENV['DB_USER'],
        $_ENV['DB_PASS']
    );
});

Dependencies are automatically resolved in controllers.

---

✅ Validation

Example:

$request->validate([
'name' => ['required','min:3'],
'email' => ['required','email'],
'price' => ['numeric']
]);

---

🔒 Security

Muta includes multiple security layers:

• CSRF Protection
• XSS Sanitization
• SQL Injection Prevention
• Rate Limiting
• Server-side Validation
• Security Headers
• Output Escaping
• Secure Error Handling

---

🖥 CLI Commands

php muta.php make:controller UserController
php muta.php make:model User
php muta.php make:middleware AuthMiddleware
php muta.php make:migration create_users_table
php muta.php migrate
php muta.php install:auth

---

🗃 Database Migrations

Create migration:

php muta.php make:migration create_products_table

Run migrations:

php muta.php migrate

---

🔑 Authentication Scaffold

Generate authentication system:

php muta.php install:auth

This creates:

• AuthController
• User Model
• Login View
• Signup View
• Authentication Middleware

---

⚠ Error Handling

Exception	HTTP Code
PageNotFoundException	404
CsrfException	403
Database Exceptions	500
Generic Exceptions	500

---

🔄 Request Lifecycle

Client
  ↓
.htaccess
  ↓
public/index.php
  ↓
Bootstrap
  ↓
Router
  ↓
Middleware
  ↓
Controller
  ↓
Model
  ↓
View
  ↓
Response

---

🤝 Contributing

Steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your branch
5. Open a Pull Request

---

📄 License

This project is open source and free to use for personal or commercial applications.

Muta Framework
Simple • Secure • Fast