Alxarafe Microframework – Technical Reference

Alxarafe is a PHP 8.2+ microframework engineered for rapid development of modular web applications and RESTful APIs. It provides a thin, opinionated layer over industry-standard components (Illuminate ORM, Blade templating, Symfony Translation) while strictly following the Convention over Configuration philosophy.

Design Principles

Principle	Description
Convention over Configuration	Controllers, models, migrations and templates are discovered automatically by scanning PSR-4 namespaces. No route files to maintain.
Modular by Default	Every feature ships as a Module (Modules\), each containing its own Controllers, Models, Migrations, Seeders, and Templates.
Leverage, Don't Reinvent	Database layer = Illuminate/Eloquent. Templates = Blade. Translations = Symfony/Translation. Authentication = JWT (Firebase PHP-JWT).
Attribute-Driven Metadata	PHP 8 Attributes (#[Menu], #[ApiRoute], #[RequireRole], #[ModuleInfo]) declaratively define routing, permissions, and module metadata.
Component Architecture	UI forms are assembled programmatically from Field, Container, and Filter components — not hard-coded HTML.

System Requirements

• PHP ≥ 8.2
• Composer
• Required extensions: ext-pdo, ext-json, ext-openssl
• Database: MySQL 5.7+ / MariaDB 10.3+ or PostgreSQL 12+

Quick Start

New Project (Recommended)

composer create-project alxarafe/alxarafe-template my-app
cd my-app
cp .env.example .env
# Edit .env with your database credentials
php bin/run_migrations.sh

Add to Existing Project

composer require alxarafe/alxarafe

Then create the expected directory structure (see Architecture).

Docker Development

cp .env.example .env
./bin/docker_start.sh
./bin/run_migrations.sh
# Access at http://localhost:8081

Project Structure

my-project/
├── config/
│   └── config.json          # Global configuration (DB, security, language)
├── public/                  # Web server Document Root
│   ├── index.php            # Entry point → Dispatcher::run()
│   └── .htaccess            # URL rewrite rules
├── Modules/                 # Application modules (Modules\ namespace)
│   └── MyModule/
│       ├── Controller/      # *Controller.php → Web routes
│       ├── Model/           # Eloquent models
│       ├── Api/             # *Controller.php → API routes
│       ├── Migrations/      # Database migrations
│       ├── Seeders/         # Data seeders
│       └── Templates/       # Blade views
├── templates/               # Shared Blade templates & layouts
├── themes/                  # Theme overrides
└── vendor/                  # Dependencies (includes alxarafe/alxarafe)
    └── alxarafe/alxarafe/
        └── src/
            ├── Core/        # Framework kernel (Alxarafe\ namespace)
            └── Modules/     # Core modules (Modules\ namespace)

Documentation Index

Fundamentals

Document	Description
Architecture & Directory Structure	PSR-4 namespaces, directory responsibilities, dependency graph
Request Lifecycle	Complete flow from index.php to HTTP response

API Reference

Document	Description
Attributes	#[ApiRoute], #[Menu], #[ModuleInfo], #[RequireModule], #[RequirePermission], #[RequireRole]
Controllers	GenericController → ViewController → Controller → ResourceController hierarchy
Models & Traits	Model, DtoTrait, HasAuditLog
Config & Database	Config, Database, Seeder, Template, BladeContainer
Component Fields	15 field types for form generation
Component Containers	Panel, Tab, TabGroup, Row, Separator, HtmlContent
Component Filters	TextFilter, SelectFilter, DateRangeFilter, etc.
Component Workflow	StatusWorkflow, StatusTransition
Lib Layer	Auth, Functions, Messages, Router, Routes, Trans
Service Layer	HookService, EmailService, PdfService, API services, Markdown
Tools Layer	Dispatcher, Debug, ModuleManager, DependencyResolver

Guides

Document	Description
Admin Module Reference	Bundled Admin module: auth, users, roles, permissions, config, migrations
Advanced Usage	Creating modules, hooks, custom fields, themes, JWT, i18n
Template Engine	Blade integration and template discovery
Template Schema	Component-based view structure
Extensible Tabs	Conditional and dynamic tab system
Theme Architecture	Asset pipeline and theme overrides
Theme System	Theme installation and customization
Menu Manager	Attribute-driven menu system
ResourceController Lifecycle	CRUD lifecycle in detail
API Development	REST APIs with JWT authentication
Testing Guide	PHPUnit, PHPStan, Psalm configuration
Docker Setup	Docker development environment
Publishing Guide	Versioning and Packagist publishing
Contribution Guide	How to contribute

License

Alxarafe is released under the GNU General Public License v3.0+ (GPL-3.0-or-later).