Introduction

ZephyrPHP is a lightweight, fast, and secure PHP framework designed for developers who value simplicity and performance. Light as a breeze, fast as the wind.

What is ZephyrPHP?

ZephyrPHP is a modern MVC framework built for PHP 8.2+ that provides everything you need to build robust web applications without the bloat. With a minimal core footprint and a truly modular architecture, it's one of the lightest full-featured frameworks available.

Unlike monolithic frameworks, ZephyrPHP starts with a lean core containing only the essentials: routing, controllers, views, validation, and session management. Need a database? Authentication? Caching? Install only what you need as separate Composer packages.

Key Features

• Lightning Fast - Minimal core with zero bloat, only load what you need. No framework overhead.
• Secure by Default - CSRF protection, input sanitization, password hashing (Argon2id), security headers, encryption, and file upload validation built-in
• Elegant Routing - Expressive routing with named routes, groups, resource routes, model binding, constraints, and domain routing
• Modular Architecture - Install only the modules you need: database (Doctrine ORM), auth (Session & JWT), authorization, cache, API, mail, and queue
• Powerful Validation - 40+ validation rules with custom messages, nested validation, and field-specific errors
• Twig Templates - Clean, secure templating with inheritance, components, view composers, and production caching
• Dependency Injection - PSR-11 container with autowiring, contextual binding, and a unique weather-themed "Zephyr API" (breeze(), storm(), gale(), etc.)
• Advanced Security - Rate limiting with multiple drivers, CSRF tokens, password hashing, encryption, security headers (CSP, HSTS, etc.)
• Session Management - Flash messages, CSRF tokens, old input, error bags, and secure session configuration
• Rich HTTP Layer - Request input casting (bool, int, float, date), content negotiation, file uploads, and comprehensive Response builder with CORS, caching headers, cookies, downloads, and streaming
• Craftsman CLI - 25+ commands to generate controllers, models, middleware, CRUD, manage modules, run migrations, and more
• Asset Management - Multiple versioning strategies (timestamp, hash, manifest), CDN integration, SRI hashes, asset collections, and Vite/Webpack support
• Exception Handling - Custom exception handlers, field-specific database error messages, debug vs production modes, and exception logging
• Modern PHP - Built for PHP 8.2+ with strict types, named arguments, attributes, and modern coding standards

Requirements

Before you begin, ensure your system meets these requirements:

Requirement	Version	Notes
PHP	8.2 or higher	Strict typing, named arguments, attributes
Composer	2.0 or higher	Package management
Extensions	PDO, mbstring, openssl, json	Core functionality
Optional	Redis, APCu	For caching and sessions

Architecture

ZephyrPHP follows the Model-View-Controller (MVC) architectural pattern with a service container at its core:

• Models - Represent your data and business logic (via the optional zephyrphp/database module with Doctrine ORM)
• Views - Twig templates that render your HTML responses with template inheritance and view composers
• Controllers - Handle HTTP requests with automatic dependency injection and coordinate between models and views
• Container - PSR-11 service container manages dependencies with autowiring, singletons, factories, and contextual binding
• Middleware - HTTP middleware pipeline for authentication, authorization, rate limiting, and custom logic
• Modules - Optional packages that extend the framework (database, auth, cache, etc.)

Request Lifecycle

Understanding the request lifecycle helps you know where to place your code:

1. Entry Point - Request enters via public/index.php
2. Bootstrap - bootstrap/app.php runs (if exists) for custom exception handlers and configuration
3. Application Start - The Application class initializes:
   • Service container setup
   • Configuration loading
   • Module discovery and loading
   • Session initialization
   • Logging setup
   • Security headers application
4. Route Matching - Router matches the request URI and HTTP method to a registered route
5. Middleware Execution - Middleware pipeline runs (auth, CSRF, rate limiting, etc.)
6. Controller Resolution - Container resolves the controller with autowired dependencies
7. Method Invocation - Controller method is called with route parameters and dependencies
8. Response - Controller returns a Response object which is sent to the client

Core vs Modules

ZephyrPHP's architecture separates essential features from optional ones:

Core Features (Always Available)

• Routing with constraints and model binding
• Controllers with base functionality
• Request and Response handling
• Twig view rendering
• Validation (40+ rules)
• Session management and flash messages
• CSRF protection
• Security headers (CSP, HSTS, etc.)
• Input sanitization
• Password hashing
• File upload validation
• Encryption
• Service container (DI)
• Exception handling
• Logging
• Asset management
• Helper functions

Optional Modules (Install via Composer)

• zephyrphp/database - Doctrine ORM, query builder, migrations
• zephyrphp/auth - Session and JWT authentication
• zephyrphp/authorization - Gates and policies for permissions
• zephyrphp/cache - File, Redis, APCu, Array drivers
• zephyrphp/api - API resources and responses
• zephyrphp/mail - Email with SMTP, Mail, Log drivers
• zephyrphp/queue - Background jobs with Sync, Database, Redis, File drivers

Getting Help

If you need help with ZephyrPHP, here are some resources:

• Installation Guide - Get up and running in minutes
• GitHub Repository - Report issues and contribute
• GitHub Discussions - Ask questions and share ideas
• Packagist - View package details and versions