README

Note: This repo contains the core of the framework. The application template can be found at webfiori/app.

Overview

WebFiori is a modular, object-oriented PHP framework designed for building secure web applications and APIs. It provides a complete toolkit — routing, middleware, authorization, database management, job queues, and more — while remaining lightweight and free of heavy external dependencies.

Motivation

WebFiori is designed around two architectural decisions:

Self-contained ecosystem. Each component (HTTP, database, cache, sessions, mail, queue, CLI, authorization) is an independent library with no external runtime dependencies. This eliminates transitive dependency conflicts and simplifies security auditing.
Interface-driven extensibility. Storage backends for sessions, cache, queues, and authorization are defined by interfaces. Swap implementations without modifying application code.

The framework provides the orchestration layer. The libraries can be used together as a full stack or independently in any PHP project.

Requirements

PHP 8.1 or later
Extensions: json, mbstring, fileinfo, openssl
Composer

Supported PHP Versions

PHP Version	Status
8.1
8.2
8.3
8.4
8.5

Quick Start

composer create-project webfiori/app my-project
cd my-project
php -S localhost:8080 -t public

Key Features

Routing & HTTP

Route groups, URI parameters, and middleware assignment
OpenAPI 3.1 specification generation from annotated controllers

Security

CSRF protection middleware with automatic token injection
CORS middleware with per-route configuration
Rate limiting with configurable windows and trusted IPs
Session encryption at rest (AES-256-GCM)
Maintenance mode with IP allowlisting and Retry-After headers

Authorization

Role-Based Access Control (RBAC) with role inheritance
Attribute-Based Access Control (ABAC) with policy evaluation
Database-backed or in-memory storage for roles and permissions
#[PreAuthorize] and #[RequiresAuth] attributes for declarative access control

Database

Query builder supporting MySQL, MSSQL, and SQLite
Schema migrations with run, rollback, dry-run, fresh, and status commands
Database seeders
Connection management with environment variable resolution

Middleware

Priority-based execution with dependency resolution
Before, after, and after-send lifecycle hooks
Middleware groups for bulk assignment to routes
Built-in: session, CSRF, CORS, rate limiting, caching, maintenance mode, authorization

Job Queue

Dispatching with priority and delayed execution
Automatic retry with configurable attempts and backoff
Payload encryption (AES-256-GCM) via environment key
Failed job tracking and retry commands
Pluggable storage backends via QueueStorage interface

Dependency Injection

Container with bind(), singleton(), and instance() registration
Automatic constructor dependency resolution
Integrated with framework core services

Task Scheduling

CRON-based background task execution
Scheduler daemon for development environments
Task arguments and conditional execution

Observability

Health check system with HTTP endpoint (200/503)
Built-in checks for cache and storage availability
Extensible via HealthCheckInterface
Structured file-based logging with daily rotation and level filtering

Additional Capabilities

Internationalization (i18n) with LTR/RTL support
Theming system for multiple UI variants
Programmatic DOM manipulation in PHP
Templated HTML email delivery with attachments
CLI scaffolding commands for controllers, middleware, migrations, and more
Event dispatcher for decoupled application components
Pluggable cache layer with full-response and HTTP caching (ETag/304)
Environment variable resolution in configuration (env: prefix)
File upload handling with validation

Architecture

WebFiori is composed of independent, interface-driven packages. Storage backends for sessions, cache, queues, and authorization are pluggable — implement the interface and swap the default.

Request lifecycle: Request → Middleware (before) → Route Dispatch → Middleware (after) → Response → Middleware (afterSend)