Alxarafe Microframework – Referencia Técnica

Alxarafe es un microframework PHP 8.2+ diseñado para el desarrollo rápido de aplicaciones web modulares y APIs RESTful. Proporciona una capa delgada y con opinión sobre componentes estándar de la industria (Illuminate ORM, Blade, Symfony Translation) siguiendo estrictamente la filosofía de Convención sobre Configuración.

Principios de Diseño

Principio	Descripción
Convención sobre Configuración	Controladores, modelos, migraciones y plantillas se descubren automáticamente escaneando namespaces PSR-4. No hay archivos de rutas que mantener.
Modular por Defecto	Cada funcionalidad se empaqueta como un Módulo (Modules\), cada uno con sus propios Controllers, Models, Migrations, Seeders y Templates.
Reutilizar, No Reinventar	Capa de datos = Illuminate/Eloquent. Plantillas = Blade. Traducciones = Symfony/Translation. Autenticación = JWT (Firebase PHP-JWT).
Metadatos vía Atributos	Los Atributos PHP 8 (#[Menu], #[ApiRoute], #[RequireRole], #[ModuleInfo]) definen declarativamente rutas, permisos y metadatos de módulos.
Arquitectura de Componentes	Los formularios UI se ensamblan programáticamente a partir de componentes Field, Container y Filter — no HTML codificado a mano.

Requisitos del Sistema

• PHP ≥ 8.2
• Composer
• Extensiones requeridas: ext-pdo, ext-json, ext-openssl
• Base de datos: MySQL 5.7+ / MariaDB 10.3+ o PostgreSQL 12+

Inicio Rápido

Nuevo Proyecto (Recomendado)

composer create-project alxarafe/alxarafe-template mi-app
cd mi-app
cp .env.example .env
# Editar .env con las credenciales de base de datos
php bin/run_migrations.sh

Agregar a un Proyecto Existente

composer require alxarafe/alxarafe

Luego crear la estructura de directorios esperada (ver Arquitectura).

Desarrollo con Docker

cp .env.example .env
./bin/docker_start.sh
./bin/run_migrations.sh
# Acceder en http://localhost:8081

Estructura del Proyecto

mi-proyecto/
├── config/
│   └── config.json          # Configuración global (BD, seguridad, idioma)
├── public/                  # Document Root del servidor web
│   ├── index.php            # Punto de entrada → Dispatcher::run()
│   └── .htaccess            # Reglas de reescritura URL
├── Modules/                 # Módulos de aplicación (namespace Modules\)
│   └── MiModulo/
│       ├── Controller/      # *Controller.php → Rutas web
│       ├── Model/           # Modelos Eloquent
│       ├── Api/             # *Controller.php → Rutas API
│       ├── Migrations/      # Migraciones de base de datos
│       ├── Seeders/         # Seeders de datos
│       └── Templates/       # Vistas Blade
├── templates/               # Plantillas Blade compartidas y layouts
├── themes/                  # Sobrescrituras de temas
└── vendor/                  # Dependencias (incluye alxarafe/alxarafe)
    └── alxarafe/alxarafe/
        └── src/
            ├── Core/        # Kernel del framework (namespace Alxarafe\)
            └── Modules/     # Módulos core (namespace Modules\)

Índice de Documentación

Fundamentos

Documento	Descripción
Arquitectura y Estructura de Directorios	Namespaces PSR-4, responsabilidad de directorios, grafo de dependencias
Ciclo de Vida de una Petición	Flujo completo desde index.php hasta la respuesta HTTP

Referencia de API

Documento	Descripción
Atributos	#[ApiRoute], #[Menu], #[ModuleInfo], #[RequireModule], #[RequirePermission], #[RequireRole]
Controladores	Jerarquía GenericController → ViewController → Controller → ResourceController
Modelos y Traits	Model, DtoTrait, HasAuditLog
Config y Base de Datos	Config, Database, Seeder, Template, BladeContainer
Campos de Componentes	15 tipos de campos para generación de formularios
Contenedores de Componentes	Panel, Tab, TabGroup, Row, Separator, HtmlContent
Filtros de Componentes	TextFilter, SelectFilter, DateRangeFilter, etc.
Workflow de Componentes	StatusWorkflow, StatusTransition
Capa Lib	Auth, Functions, Messages, Router, Routes, Trans
Capa de Servicios	HookService, EmailService, PdfService, servicios API, Markdown
Capa de Herramientas	Dispatcher, Debug, ModuleManager, DependencyResolver

Guías

Documento	Descripción
Referencia del Módulo Admin	Módulo Admin integrado: auth, usuarios, roles, permisos, config, migraciones
Uso Avanzado	Crear módulos, hooks, campos personalizados, temas, JWT, i18n
Motor de Plantillas	Integración Blade y descubrimiento de plantillas
Esquema de Plantillas	Estructura de vistas basada en componentes
Pestañas Extensibles	Sistema de pestañas condicionales y dinámicas
Arquitectura de Temas	Pipeline de assets y sobrescrituras de temas
Sistema de Temas	Instalación y personalización de temas
Gestor de Menús	Sistema de menús basado en atributos
Ciclo de Vida del ResourceController	Ciclo CRUD en detalle
Desarrollo de APIs	APIs REST con autenticación JWT
Guía de Testing	Configuración de PHPUnit, PHPStan, Psalm
Docker	Entorno de desarrollo Docker
Guía de Publicación	Versionado y publicación en Packagist
Guía de Contribución	Cómo contribuir al proyecto

Licencia

Alxarafe se distribuye bajo la GNU General Public License v3.0+ (GPL-3.0-or-later).