README

Fubber is a modern PHP application framework designed around developer productivity, extensibility, and a clean separation of concerns. It provides powerful building blocks such as controllers, configuration, dependency injection, routing, and instrumentation for performance and debugging.

This README gives you an eagle’s‑eye view of the framework. For deeper dives, see the linked documents in the docs/ folder.

✨ Features

• Controller‑centric architecture – define routes, lifecycle hooks, and cron jobs in one place.
• Configuration system – layered config loading with environment awareness.
• Dependency injection container – flexible, annotation‑driven DI.
• Routing – expressive HTTP routing with middleware and exception mapping.
• Instrumentation – built‑in tools for profiling, benchmarking, and exception annotation.
• Bundles – modular extension system with manifests for reusable packages.
• Developer ergonomics – sensible defaults, modern helper methods, and PSR‑compatible interfaces.

🏗️ High-Level Architecture

                        ┌────────────────────┐
                        │   Application      │
                        │   (Your Code)      │
                        └─────────┬──────────┘
                                  │
                        ┌─────────▼──────────┐
                        │      Kernel        │
                        │  (phases, hooks)   │
                        └─────────┬──────────┘
                                  │
     ┌───────────────┬────────────┴─────────────┬───────────────┐
     │               │                          │               │
┌────▼────┐   ┌──────▼──────┐          ┌────────▼────────┐ ┌─────▼─────┐
│ Config  │   │ Controllers │          │ Container       │ │ Http      │
│ Env     │   │ Lifecycle   │          │ (DI, Services)  │ │ Router    │
└────┬────┘   └──────┬──────┘          └────────┬────────┘ └─────┬─────┘
     │               │                          │                │
     ▼               ▼                          ▼                ▼
 .env + php   Routes, init(), call()      Services, scopes   Middleware,
  settings      + Cron tasks               Factories         Exception handling

📂 Documentation

• Getting Started

• Controllers

  • Abstract Controller
• Configuration
• Dependency Injection Container
• HTTP & Routing
• Instrumentation
• Bundles

🚀 Quick Example

use Fubber\Kernel\AbstractController;

final class HelloController extends AbstractController
{
    public function routes(): array {
        return [
            "GET /hello" => fn() => $this->json(["message" => "Hello, World!"]),
        ];
    }
}

🔗 Next Steps

• Start with Getting Started to spin up a new project.
• Explore Controllers to learn how to handle routes and lifecycle hooks.
• Use Instrumentation to measure and debug your application.

Core Guides

1. Getting Started

   • Installation & Requirements
   • Directory Structure
   • First Controller

2. Kernel & Phases

   • Boot Process
   • Phase Handlers
   • Hooks & Triggers

3. Configuration

   • Environment (.env)
   • Config files (config/*.php)
   • Adding config paths

4. Controllers

   • Lifecycle (load, init, call)
   • Static vs Instance controllers
   • Adding Routes

5. HTTP Layer

   • Router
   • Middleware (PSR-15)
   • Exception Handling

6. Dependency Injection

   • Services & Scopes
   • Autowiring
   • Container API

Advanced Topics

• Cron Jobs
• Instrumentation (logging, metrics, debugging)
• Extending the Kernel (KernelExtension, custom phases)
• Microcache for lightweight caching
• FileSystem abstraction

Reference

• API Docs (autogenerated)
• Examples & Recipes

🗺️ Next Steps

• Getting Started Guide
• Controllers Overview
• Configuration Guide
• HTTP & Routing
• Dependency Injection
• Extending the Kernel

🚀 Philosophy

Fubber Framework embraces:

• Explicit over implicit — lifecycle and phases are visible and traceable.
• Convention with escape hatches — config drives the app, but you can override at will.
• Performance awareness — instrumentation and microcache are built in.
• Security by default — environment variables are scrubbed after import, and sensitive files stay outside the web root.