118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# Koneko ERP - Cache Helper Guide
|
|
|
|
> ✨ Esta guía detalla el uso correcto del sistema de cache en Koneko ERP, basado completamente en el helper `cache_manager()`, sin necesidad de interactuar con las clases internas como `KonekoCacheManager` o `LaravelCacheManager`.
|
|
|
|
---
|
|
|
|
## 🔎 Filosofía
|
|
|
|
* Toda interacción de componentes con el sistema de cache debe realizarse exclusivamente mediante el helper `cache_manager()`.
|
|
* Las clases internas son consideradas **@internal**, y no deben ser accedidas directamente por desarrolladores de componentes.
|
|
* El sistema permite configuración jerárquica basada en namespace del componente, grupo lógico de datos y claves individuales.
|
|
|
|
---
|
|
|
|
## 🔍 Sintaxis del Helper
|
|
|
|
```php
|
|
cache_manager(string $component = 'admin', string $group = 'cache')
|
|
```
|
|
|
|
Retorna una instancia segura del gestor para el componente y grupo indicados. Ejemplos:
|
|
|
|
```php
|
|
cache_manager('admin', 'avatar')->enabled();
|
|
cache_manager('website', 'menu')->ttl();
|
|
cache_manager('website', 'html')->flush();
|
|
```
|
|
|
|
---
|
|
|
|
## ⚖️ Jerarquía de Configuración
|
|
|
|
Las operaciones de cache respetan la siguiente jerarquía al determinar configuraciones:
|
|
|
|
1. `koneko.{componente}.{grupo}.ttl` / `enabled`
|
|
2. `koneko.{componente}.cache.ttl` / `enabled`
|
|
3. `koneko.cache.ttl` / `enabled`
|
|
|
|
Esto permite granularidad sin perder coherencia global.
|
|
|
|
---
|
|
|
|
## 📃 Métodos Disponibles
|
|
|
|
| Método | Descripción |
|
|
| ------------------------ | ------------------------------------------------------------- |
|
|
| `key(string $suffix)` | Genera clave de cache completa con prefijos |
|
|
| `config($key, $default)` | Accede a configuraciones con prefijo aplicado |
|
|
| `ttl()` | TTL efectivo (en segundos) |
|
|
| `enabled()` | Determina si el cache está habilitado para el contexto actual |
|
|
| `flush()` | Limpia el grupo de cache completo si el driver lo permite |
|
|
| `driver()` | Devuelve el driver de cache actual |
|
|
| `shouldDebug()` | Evalúa si se encuentra en modo debug para cache |
|
|
| `registerDefaults()` | Registra valores default para ttl y enabled si no existen |
|
|
|
|
---
|
|
|
|
## 🚀 Ejemplos de Uso
|
|
|
|
### Validar TTL efectivo
|
|
|
|
```php
|
|
$ttl = cache_manager('website', 'menu')->ttl();
|
|
```
|
|
|
|
### Verificar si está habilitado
|
|
|
|
```php
|
|
if (cache_manager('admin', 'avatar')->enabled()) {
|
|
// Proceder con cache
|
|
}
|
|
```
|
|
|
|
### Limpiar cache con soporte para etiquetas
|
|
|
|
```php
|
|
cache_manager('website', 'html')->flush();
|
|
```
|
|
|
|
---
|
|
|
|
## ⚠️ Buenas Prácticas
|
|
|
|
* **No** uses directamente la clase `KonekoCacheManager`.
|
|
* **No** accedas directamente al sistema `Cache::` sin pasar por el helper.
|
|
* **No** asumas estructura de clave, usa `->key()`.
|
|
* **Sí** configura `koneko.{componente}.{grupo}.ttl` en tu archivo `config()` si tu componente lo necesita.
|
|
|
|
---
|
|
|
|
## 🔍 Debug y Diagnóstico
|
|
|
|
Ejecuta:
|
|
|
|
```bash
|
|
php artisan koneko:cache --component=website --group=html --ttl
|
|
php artisan koneko:cache --component=admin --group=avatar --flush
|
|
```
|
|
|
|
El comando mostrará información relevante para depuración sin exponer clases internas.
|
|
|
|
---
|
|
|
|
## 🚧 Futura Expansión
|
|
|
|
* Registro de tags
|
|
* TTLs dinámicos
|
|
* Integración con eventos y auditoría
|
|
* Modo "read-only" para ambientes cacheados
|
|
|
|
---
|
|
|
|
## 🌟 Conclusión
|
|
|
|
Este sistema garantiza modularidad, extensibilidad y seguridad. El helper `cache_manager()` es la única puerta de entrada para desarrolladores y debe usarse exclusivamente para mantener la integridad del ecosistema.
|
|
|
|
> ✅ Si necesitas agregar un nuevo grupo de cache, simplemente define su configuración y comienza a usar el helper, sin necesidad de modificar clases o contratos.
|