OXIRA Core Framework

Documentación Técnica OXIRA Core Framework v2

OXIRA Core v2 es una base MVC PHP pensada para reutilizarse en cualquier tipo de proyecto: webs corporativas, tiendas, blogs, paneles administrativos, POS, APIs y sistemas internos.

Objetivo principal: crear nuevos proyectos sin rehacer arquitectura, seguridad ni routing desde cero.

Principios del framework

  • Convención sobre configuración para desarrollo rápido.
  • Configuración central para seguridad por áreas.
  • Front público por defecto para facilitar SEO y contenido.
  • Soporte para áreas privadas por rol (admin, user, pos, etc.).
  • Subcarpetas ilimitadas para escalar módulos.

Instalación

  1. Descomprimir el proyecto en servidor local o producción.
  2. Copiar .env.example a .env.
  3. Ajustar base de datos, URL y base path.

Ejemplo local (Laragon)

APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost/education
APP_BASE_PATH=/education

DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=oxira_micro
DB_USER=root
DB_PASS=

Ejemplo producción

APP_ENV=production
APP_DEBUG=false
APP_URL=https://framework.oxira.pe
APP_BASE_PATH=
SESSION_SECURE=true

Arquitectura general

El flujo central de cada request es:

index.php
  -> bootstrap.php
  -> Router (rutas explícitas + convención)
  -> Auth por área (si aplica)
  -> CSRF (si aplica)
  -> Controller@method
  -> View o JSON
Diagrama del flujo de request en OXIRA Core

Routing automático y rutas explícitas

1) Rutas explícitas por método HTTP

Definidas en config/routes.php.

'GET' => [
  '/admin/login' => [Admin\LoginController::class, 'index'],
],
'POST' => [
  '/admin/login/submit' => [Admin\LoginController::class, 'submit'],
]

2) Fallback por convención

Si no hay ruta explícita, el router mapea por estructura de carpetas.

/admin/settings/currencies/1/edit
=> App\Controllers\Admin\Settings\CurrenciesController@edit(1)

/pos/ventas/caja/abrir
=> App\Controllers\Pos\Ventas\CajaController@abrir()

Puedes combinar ambos estilos: explícitas donde importa control HTTP, convención para el resto.

Seguridad por áreas

La seguridad no se configura en cada controlador, sino por área en config/security.php. Así evitas errores repetitivos y mantienes consistencia entre proyectos.

Config base

'reserved_areas' => ['admin', 'user', 'api'],

'protected_areas' => [
  'admin' => 'admin',
  'user'  => 'user',
],

'auth_redirects' => [
  'admin' => '/admin/login',
  'user'  => '/user/login',
],

'auth_exceptions' => [
  'admin' => ['login', 'logout'],
  'user'  => ['login', 'logout'],
]

Si un área no está en protected_areas, esa área es pública. Por eso el front se mantiene sin login por defecto.

Configuración central del framework

Los archivos de config/ separan responsabilidades y evitan lógica dispersa:

  • config/app.php: app name, URL, debug, timezone, base path y sesión.
  • config/security.php: áreas reservadas, roles por área, redirecciones y CSRF.
  • config/routes.php: rutas explícitas por método HTTP.
  • config/database.php: driver MySQL/SQLite y conexión.
  • config/auth.php: credenciales demo o defaults de autenticación.
// Ejemplo: activar un área privada para staff
'protected_areas' => [
  'admin' => 'admin',
  'staff' => 'staff',
],
'auth_redirects' => [
  'staff' => '/staff/login',
],
'auth_exceptions' => [
  'staff' => ['login', 'logout'],
]

Cómo crear áreas personalizadas (ej. /pos)

Para agregar un nuevo panel privado como /pos:

  1. Agregar pos en reserved_areas.
  2. Definir su rol en protected_areas.
  3. Definir su login en auth_redirects.
  4. Permitir login/logout en auth_exceptions.
  5. Crear carpetas Controllers/Pos y Views/pos.
// security.php
'reserved_areas' => ['admin', 'user', 'api', 'pos'],
'default_controllers' => [
  'pos' => 'Dashboard',
],
'protected_areas' => [
  'pos' => 'pos',
],
'auth_redirects' => [
  'pos' => '/pos/login',
],
'auth_exceptions' => [
  'pos' => ['login', 'logout'],
]
app/Controllers/Pos/LoginController.php
app/Controllers/Pos/LogoutController.php
app/Controllers/Pos/DashboardController.php
app/Views/pos/layout.php
app/Views/pos/login.php
app/Views/pos/dashboard/index.php

API libre o API con login

API pública (por defecto)

// security.php
'protected_areas' => [
  'admin' => 'admin',
  'user'  => 'user',
  // api no aparece => pública
]

API privada (requiere rol)

// security.php
'protected_areas' => [
  'admin' => 'admin',
  'user'  => 'user',
  'api'   => 'admin',
],
'auth_redirects' => [
  'api' => '/admin/login',
]

Subcarpetas ilimitadas

Puedes construir estructuras profundas sin registrar rutas manuales para cada pantalla. 

/admin/reportes/ventas/diario/2026/02/10
=> App\Controllers\Admin\Reportes\VentasController@diario(2026, 02, 10)

/user/perfil/editar
=> App\Controllers\User\PerfilController@editar()

Esto acelera mucho proyectos grandes con múltiples subpaneles.

Base path en subcarpetas

Si trabajas en subdirectorio, por ejemplo http://localhost/education, define: 

APP_URL=http://localhost/education
APP_BASE_PATH=/education

El framework ya usa ese valor para normalizar rutas y redirecciones internas.

Despliegue recomendado

  • APP_DEBUG=false en producción.
  • HTTPS activo + SESSION_SECURE=true.
  • Configurar host canónico (sin duplicados http/www).
  • Publicar robots.txt y sitemap.xml.
  • Enviar sitemap en Google Search Console.

Checklist final para nuevos proyectos

  1. Clonar base OXIRA Core v2.
  2. Configurar .env local/prod.
  3. Definir áreas reservadas del proyecto.
  4. Marcar áreas privadas con rol y login redirect.
  5. Crear módulos por carpetas (controllers + views).
  6. Definir rutas explícitas solo donde haga falta.
  7. Validar errores 404/405/419 y flujos login/logout.
  8. Publicar landing + docs + sitemap + robots.

Con este flujo puedes arrancar rápido webs, tiendas, blogs o paneles sin perder consistencia técnica.