PHPackages                             latinexus/lx\_auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. latinexus/lx\_auth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

latinexus/lx\_auth
==================

Sistema de autenticación multi-tenancy con roles y permisos para PHP

v1.1.1(1mo ago)07MITPHPPHP ^8.3

Since Feb 10Pushed 1mo agoCompare

[ Source](https://github.com/latinexus/lx_auth)[ Packagist](https://packagist.org/packages/latinexus/lx_auth)[ RSS](/packages/latinexus-lx-auth/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (4)Dependencies (33)Versions (6)Used By (0)

LxAuth - Sistema de Autenticación y Autorización
================================================

[](#lxauth---sistema-de-autenticación-y-autorización)

Librería PHP para autenticación, roles y permisos. Trabaja contra **una única base de datos por instancia**. Ideal para arquitecturas SaaS donde cada cliente (tenant) tiene su propia base de datos.

> **Nota**: La resolución del tenant (cliente) y sus credenciales de conexión son **responsabilidad de la aplicación** que consume LX\_AUTH. LX\_AUTH recibe una conexión ya configurada y opera exclusivamente contra ella.

🚀 Características
-----------------

[](#-características)

- ✅ **Roles Jerárquicos**: Sistema de roles con herencia de permisos
- ✅ **Permisos Flexibles**: Soporte para wildcards (`users.*`, `admin:access`)
- ✅ **Autenticación JWT**: Tokens seguros para APIs
- ✅ **Middleware PSR-15**: Protección de rutas estándar
- ✅ **Throttling**: Protección contra fuerza bruta
- ✅ **Caching**: Mejora de rendimiento para roles y permisos
- ✅ **Sesiones PHP**: Gestión nativa de sesiones con "remember me"
- ✅ **Drivers Extensibles**: Soporte para múltiples bases de datos
- ✅ **Contratos e Interfaces**: Testing fácil y flexibilidad

📋 Requisitos
------------

[](#-requisitos)

- PHP >= 8.3
- Extensiones: ext-json, ext-openssl, ext-pdo
- Composer

🛠️ Instalación
--------------

[](#️-instalación)

```
composer install
```

🗄️ Esquema de Base de Datos
---------------------------

[](#️-esquema-de-base-de-datos)

Cada base de datos donde opere LX\_AUTH debe tener las siguientes tablas:

TablaDescripción`users`Usuarios del sistema`roles`Roles jerárquicos`permissions`Permisos con wildcards`role_user`Relación usuarios-roles`permission_role`Relación roles-permisos`permission_user`Permisos directos a usuarios`persistences`Sesiones persistentes### Migraciones

[](#migraciones)

```
php migrate.php                    # SQLite (desarrollo/pruebas)
php migrate_mysql.php              # MySQL/MariaDB
php migrate_mysql.php --fresh      # Recrear tablas
php migrate_mysql.php --rollback   # Revertir
```

🔧 Configuración Básica
----------------------

[](#-configuración-básica)

```
use LxAuth\LxAuth;
use LxAuth\Drivers\Database\EloquentDriver;
use Illuminate\Database\Capsule\Manager as Capsule;

// 1. Tu app resuelve el tenant y configura la conexión a su BD
$capsule = new Capsule;
$capsule->addConnection([
    'driver'   => 'mysql',
    'host'     => '...',
    'database' => E_DB_NAM,    // 'cargo_prueba'
    'username' => E_DB_USR,    // 'cargo_prueba_usr'
    'password' => E_DB_PWD,
    'charset'  => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
]);
$capsule->setAsGlobal();
$capsule->bootEloquent();

// 2. Pasar la instancia de Capsule a LX_AUTH
EloquentDriver::setCapsule($capsule);

// 3. Inicializar LX_AUTH
$auth = LxAuth::getInstance([
    'tokens' => [
        'jwt' => [
            'secret' => 'tu-clave-secreta',
        ],
    ],
]);
```

📚 Uso Básico
------------

[](#-uso-básico)

### Autenticación

[](#autenticación)

```
// Autenticar usuario
$user = $auth->authenticate([
    'email' => 'admin@example.com',
    'password' => 'password123'
]);

// Registrar nuevo usuario
$user = $auth->register([
    'email' => 'newuser@example.com',
    'password' => 'password123',
    'first_name' => 'John',
    'last_name' => 'Doe'
]);

// Iniciar sesión (PHP session)
$auth->login($user, remember: true);

// Verificar sesión activa
if ($auth->check()) {
    $user = $auth->user();
}

// Cerrar sesión
$auth->logout();

// Crear token JWT
$token = $auth->createToken($user, 'api');

// Validar token
$user = $auth->validateToken($token);
```

### Roles y Permisos

[](#roles-y-permisos)

```
// Asignar rol
$auth->assignRole($user, 'admin');

// Verificar rol
if ($auth->hasRole('admin')) {
    // Es administrador
}

// Otorgar permiso directo
$auth->givePermissionTo($user, 'users.create');

// Verificar permiso
if ($auth->can('users.create')) {
    // Puede crear usuarios
}

// Permisos con wildcards
if ($auth->can('users.*')) {
    // Puede hacer cualquier operación con usuarios
}
```

### Middleware PSR-15

[](#middleware-psr-15)

```
// Proteger rutas
$app->add($auth->middleware());                          // Auth requerido
$app->add($auth->permissionMiddleware('users.create'));  // Permiso específico
$app->add($auth->roleMiddleware('admin'));               // Rol específico
```

$tenantId = $auth->getTenantResolver()->resolve();

```

## 🛡️ Middleware

```php
// Middleware de autenticación
$authMiddleware = $auth->middleware(['/login', '/register']);

// Middleware de permisos
$permissionMiddleware = $auth->permissionMiddleware('users.create');

// Middleware de roles
$roleMiddleware = $auth->roleMiddleware('admin');

// Middleware de tenant
$tenantMiddleware = $auth->tenantMiddleware();

```

🧪 Testing
---------

[](#-testing)

Ejecuta las pruebas para verificar que todo funciona:

```
# Tests básicos (SQLite en memoria)
php test_simple.php              # Test básico del modelo
php test_final.php               # Test de compatibilidad completa
php test_migrations.php          # Test de migraciones con datos

# Tests específicos para MySQL/MariaDB
php test_mysql.php               # Test completo con MySQL/MariaDB

# Migraciones
php migrate.php                  # Migraciones SQLite (desarrollo)
php migrate_mysql.php            # Migraciones MySQL/MariaDB (producción)
```

📁 Estructura del Proyecto
-------------------------

[](#-estructura-del-proyecto)

```
src/
├── LxAuth.php              # Clase principal
├── Models/                 # Modelos Eloquent
│   ├── User.php
│   ├── Role.php
│   ├── Permission.php
│   └── Tenant.php
├── Services/               # Servicios del sistema
│   ├── AuthManager.php
│   ├── RoleManager.php
│   ├── PermissionManager.php
│   └── TenantResolver.php
├── Middleware/             # Middleware PSR-15
├── Drivers/               # Drivers de base de datos
└── Contracts/             # Interfaces y contratos

config/
└── lx_auth.php            # Configuración

database/
└── migrations/            # Migraciones de base de datos

tests/                     # Tests unitarios

```

🔑 Conceptos Clave
-----------------

[](#-conceptos-clave)

### Multi-Tenancy

[](#multi-tenancy)

Cada tenant tiene sus propios usuarios, roles y permisos completamente aislados.

### Roles Jerárquicos

[](#roles-jerárquicos)

Los roles pueden tener roles padre, heredando automáticamente los permisos del padre.

### Permisos con Wildcards

[](#permisos-con-wildcards)

Soporta patrones como:

- `users.create` - Crear usuarios
- `users.*` - Cualquier operación con usuarios
- `*` - Acceso total

### Drivers Extensibles

[](#drivers-extensibles)

El sistema soporta diferentes drivers de base de datos. Actualmente incluye:

- **EloquentDriver**: Para Laravel Eloquent
- Fácil extensión para Redis, MongoDB, etc.

🚨 Notas Importantes
-------------------

[](#-notas-importantes)

1. **Producción**: Remueve cualquier código de debug antes de deployar
2. **Secret Keys**: Cambia las claves JWT en producción
3. **Base de Datos**: Configura una base de datos persistente para producción
4. **Caching**: Considera Redis o Memcached para caching en producción

---

🔐 Notas sobre JWT (importante)
------------------------------

[](#-notas-sobre-jwt-importante)

LxAuth ahora usa `firebase/php-jwt` en su serie 7.x. Esta versión incluye validaciones de seguridad adicionales que pueden afectar a tokens existentes si la configuración no cumple los requisitos mínimos.

- Requisito de longitud del secret (HMAC):

    - `HS256` requiere al menos 256 bits (32 bytes)
    - `HS384` requiere al menos 384 bits (48 bytes)
    - `HS512` requiere al menos 512 bits (64 bytes)
- Si tu `LX_AUTH_JWT_SECRET` es más corto que el mínimo requerido para el algoritmo configurado, la generación de tokens fallará con una excepción. Para evitarlo, asegúrate de usar secrets suficientemente largos.
- Comando recomendado para generar un secret seguro (32 bytes hex):

```
php -r "echo bin2hex(random_bytes(32));"
```

- Sugerencia de despliegue/rotación:

    - Considera soportar temporalmente una clave secundaria (`jwt.secret_secondary`) para permitir una rotación segura sin invalidar sesiones inmediatamente; valida primero con la primaria y, si falla, intenta la secundaria.
    - Registra y renueva tokens firmados con la clave secundaria durante el período de transición.
- Validaciones añadidas en LxAuth:

    - `AuthManager` ahora valida la longitud del secret antes de llamar a la librería y sincroniza `JWT::$leeway` desde la configuración (`tokens.jwt.leeway`). Si el secret es insuficiente, se lanzará una excepción con mensaje claro.

---

📄 Licencia
----------

[](#-licencia)

MIT License - Ver archivo LICENSE para detalles.

🤝 Contribuciones
----------------

[](#-contribuciones)

¡Contribuciones son bienvenidas! Por favor sigue los estándares de código y testing.

---

**LxAuth** - Autenticación robusta y flexible para aplicaciones PHP modernas.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance91

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~47 days

Total

4

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ef07fcc93fb0e78d87e48eadfab16e2ead99a1ce78cf4ef49663a6b45ab5453c?d=identicon)[latinexus](/maintainers/latinexus)

---

Top Contributors

[![latinexus](https://avatars.githubusercontent.com/u/40701675?v=4)](https://github.com/latinexus "latinexus (17 commits)")

---

Tags

phpAuthenticationaclrolespermissionsmulti-tenant

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/latinexus-lx-auth/health.svg)

```
[![Health](https://phpackages.com/badges/latinexus-lx-auth/health.svg)](https://phpackages.com/packages/latinexus-lx-auth)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.9k20.0M1.9k](/packages/cakephp-cakephp)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[typo3/cms-core

TYPO3 CMS Core

3313.6M5.6k](/packages/typo3-cms-core)[moonshine/moonshine

Laravel administration panel

1.3k268.2k89](/packages/moonshine-moonshine)[thecodingmachine/graphqlite

Write your GraphQL queries in simple to write controllers (using webonyx/graphql-php).

5753.4M51](/packages/thecodingmachine-graphqlite)[getgrav/grav

Modern, Crazy Fast, Ridiculously Easy and Amazingly Powerful Flat-File CMS

15.6k88.1k1](/packages/getgrav-grav)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)