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:

1. 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.

2. 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)

Standard Libraries

Library	Build	Latest
HTTP
Database
CLI
Cache
UI
Mailer
File
Json
Collections
Error Handler
Container
Queue
Event
Log

Documentation

• Getting Started Guide
• API Reference

Contributing

See CONTRIBUTING.md for guidelines.

Security

To report security vulnerabilities, please email ibrahim@webfiori.com. See SECURITY.md for supported versions.

License

MIT — see LICENSE for details.