Download the PHP package sailantis/azera-framework without Composer

Lightweight by Design. Powerful in Practice.

A lightweight, fast PHP framework for building modern Web applications and CLI tools. Azera combines the best ideas from frameworks like Phalcon, CodeIgniter, Laravel and Symfony into a minimal yet powerful toolkit.

Why Azera?

Lightweight & Fast - Minimal dependencies and overhead. No bloat, just what you need.

Modern PHP - Built for PHP 8.2+, embracing type hints, named arguments, and modern patterns.

Unified Query Builder - One consistent, fluent API for all database operations, whether you're using models or raw queries.

Flexible Architecture - Use as much or as little as you need. Mix and match components freely.

Secure by Default - SQL injection protection via prepared statements, CSRF protection, encryption helpers, and security best practices built in.

Developer Friendly - Intuitive APIs, clear error messages, and comprehensive documentation.

Features

MVC Stack

• Router - Fast pattern matching with named routes, parameter validation, and middleware support
• Controllers - Clean action-based controllers with dependency injection
• Dispatcher - Flexible request dispatching with middleware pipeline
• ViewEngine - Clarity template engine with auto-escaping, template inheritance, and a filter pipeline. Other engines can be used as well, including Twig, Plates, and plain PHP templates.

Database & ORM

• Query Builder - Unified fluent interface for SELECT, INSERT, UPDATE, DELETE
• Active Record Models - Expressive model API with state tracking and typed property support
• Prepared Statements - SQL injection protection by default
• Read/Write Splitting - Built-in support for master/replica database setups
• Connection Pooling - Automatic reconnection and connection management
• Schema Introspection - Introspect database schema for dynamic models and migrations

HTTP Utilities

• Request - Normalized access to GET, POST, headers, and file uploads
• Response - Fluent response building with JSON, redirects, and status codes
• Session - Simple session management with pluggable storage handlers
• Cookies - Easy cookie handling with encryption support
• Middleware - Composable request/response filters

CLI Tools

• Console - Powerful CLI dispatcher with:
  • Auto-discovery of tasks from namespaces
  • Flexible task grouping and custom namespaces
  • Rich color output and styled help pages
  • Option parsing and argument separation
  • Built-in help and task listing
• ModelSync Task (model-sync) - Built-in CLI task for synchronizing PHP models with the database schema, generating migration/migration-like changes and optionally applying them.

Additional Features

• Validation - Fluent field rules with type coercion, nested list/object validation, and error collection
• Security - CSRF tokens, password hashing, encryption (Sodium/OpenSSL)
• Logging - Event-based logging hooks for database and application events
• Pagination - Built-in query pagination with automatic total-count queries
• Exception Handling - Structured exception hierarchy
• AppContext - Centralized service container for shared resources

Benchmarks

Azera is measured against Laravel, Symfony, Spiral, CodeIgniter 4 and CakePHP 5 on an identical full-stack workload — routing → controller → ORM query (SQLite) → template render → response — running on a real server. Two summaries are published beside the docs, one per deployment model:

As nginx + PHP-FPM — the framework boots again for every request, as PHP usually runs in production:

As a resident worker (RoadRunner) — the framework boots once and serves every request:

Each chart sums one pass over all 21 benchmarked endpoints. The full per-endpoint tables, the per-feature races and the memory charts are in the complete report covers all six frameworks.

Requirements

• PHP >= 8.2
• PDO extension (ext-pdo)
• Multibyte String extension (ext-mbstring)
• Optional: Sodium or OpenSSL extension for advanced encryption features, MongoDB extension for MongoDB ORM support

(PDO driver support is implemented for MySQL, PostgreSQL and SQLite. Other drivers may work but are not officially tested.)

Installation

Install via Composer:

Quick Start

Web Application (MVC)

Create a simple web application with routing and controllers:

Controller example:

Working with Models

Define and use Active Record style models:

Validating Input

Azera includes a fluent validation component. Fields are required by default; call ->optional() or ->default() where needed.

Or throw on failure instead of branching:

Paginating Results

Paginator wraps any Query, handles LIMIT/OFFSET, and runs an automatic total-count query.

Advanced Query Builder

Build complex queries with joins, subqueries, and aggregations.

Using Models and Sql Functions

Subqueries as Sources

A Query instance can be passed directly to ->from() or to any join method. The subquery is wrapped in parentheses automatically and its bind parameters are propagated to the outer query — no manual merging required.

Using ModelMapping for Dynamic Model References

ModelMapping lets you reference model names in queries without full Active Record classes — useful for dynamic schemas or reporting queries. See Database Queries for the complete API.

Using the Query Builder Directly on Tables

For queries that don't belong to any model, start with Query::raw() and specify the table manually:

CLI Tasks

Build command-line tools and scripts. Console auto-discovers tasks from PSR-4 namespaces, parses options, and renders color-highlighted help pages.

console.php — minimal entry point:

Create a task — extend Task, add *Action methods:

Run tasks from the command line — options are separated from positional arguments automatically:

Using Built-in Tasks

Azera includes a built-in model-sync task that synchronizes PHP models with the database schema:

model-sync all and model-sync make auto-resolve the target directory from PSR-4 entries in composer.json. See CLI Tasks for all options.

Project Structure

Recommended directory layout for Azera applications:

Documentation

Comprehensive guides and references:

• Getting Started - Set up your first Azera project
• Architecture - Understand core components and design principles
• MVC Routing - Define routes, patterns, and middleware
• Controllers & Views - Build controllers and render views
• Clarity Templates - Sandboxed template engine with auto-escaping and inheritance
• Models & ORM - Work with Active Record models
• Database Queries - Master the query builder
• HTTP Request - Handle requests, uploads, and headers
• Validation - Validate and coerce request input
• CLI Tasks - Create command-line tools
• Security - Best practices and security features
• Logging - Application and database logging
• Cookbook - Practical recipes and examples
• Benchmarks - How Azera compares to Laravel, Symfony, Spiral, CodeIgniter 4 and CakePHP 5
• API Reference - Complete API documentation

Key Concepts

AppContext - Service Container

Centralized access to shared services via a singleton service container:

Registered callables are treated as zero-argument lazy factories. They are executed on first lookup and the returned object is cached for the rest of the request lifecycle.

Middleware Pipeline

Add custom logic to the request/response cycle:

Read/Write Database Splitting

Separate read and write connections for scalability:

Development

Running Tests

Azera uses PHPUnit for testing:

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

When contributing:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Examples

Check out the examples/ directory for complete working examples:

• AdvancedQueryBuilderExample.php - Complex queries with joins, subqueries, window functions, and aggregations. Perfect for learning sophisticated query patterns.
• CompositeKeyExamples.php - Working with models that have composite primary keys, such as many-to-many junction tables and multi-tenant databases.
• ModelLoadMethodsExample.php - Using convenience methods like find(), findOne(), findAll(), exists(), and count() for retrieving model data.
• ReadWriteConnectionExample.php - Setting up separate read and write database connections for master/replica configurations and improved scalability.
• SaveCreateUpdateExample.php - Complete CRUD operations including create(), save(), delete(), and tracking changes with hasChanged().
• SqlNodeExample.php - Advanced SQL expressions using the Sql class for raw SQL, functions, subqueries, and complex conditions within the query builder.
• ModelSyncExample/ - A CLI application example demonstrating task auto-discovery, custom namespaces, and the built-in model-sync task features.

Philosophy

Azera is designed with these principles:

• Simplicity over magic - Explicit is better than implicit
• Performance - Minimal overhead and memory footprint
• Standards - PSR-compliant where applicable
• Flexibility - Use what you need, ignore the rest
• Security - Secure by default, not as an afterthought

Acknowledgments

Azera draws inspiration from:

• Phalcon - Speed and C-based architecture concepts
• CodeIgniter - Simplicity and developer-friendly APIs
• Laravel - Elegant syntax and query builder design

About the Name

Azera is named after Andi Gutmans, Zeev Suraski, and Rasmus Lerdorf — the founders of PHP.

The little bird on the Azera logo is a Merlin falcon — a small, fast, and agile raptor, just like the framework itself: lightweight, focused, and built for speed. It is also a reference to Phalcon, which strongly influenced Azera’s design.

License

MIT License - see LICENSE file for details.

Built with ❤️ for developers who value security and performance