162 lines
3.4 KiB
Markdown
162 lines
3.4 KiB
Markdown
# Koneko Settings Helper Guide
|
|
|
|
Guía oficial de uso para `settings()` dentro del ecosistema Koneko ERP.
|
|
|
|
---
|
|
|
|
## 📁 Filosofía General
|
|
|
|
KonekoSettingManager es una clase interna (@internal) encargada de gestionar configuraciones de componentes y módulos del ecosistema de forma centralizada, modular y cacheable. No debe ser usada directamente.
|
|
|
|
### Acceso siempre mediante el helper global:
|
|
|
|
```php
|
|
settings()->get('clave');
|
|
settings()->set('clave', 'valor');
|
|
```
|
|
|
|
---
|
|
|
|
## ⚖️ Jerarquía de Namespace (Prioridad de Resolución)
|
|
|
|
```text
|
|
componentNamespace (ej: admin, website)
|
|
└️ module_slug (ej: avatar, seo, menu)
|
|
└️ key
|
|
```
|
|
|
|
Ejemplo real:
|
|
|
|
```text
|
|
koneko.admin.avatar.cache.ttl
|
|
```
|
|
|
|
---
|
|
|
|
## ✨ Métodos Disponibles
|
|
|
|
### `self(?string $subNamespace = null)`
|
|
|
|
Se vincula automáticamente al componente activo según el contexto del módulo actual.
|
|
|
|
```php
|
|
settings()->self()->get('cache.ttl');
|
|
```
|
|
|
|
### `in(string $namespace)`
|
|
|
|
Permite establecer un namespace manual.
|
|
|
|
```php
|
|
settings()->in('admin.avatar')->get('enabled');
|
|
```
|
|
|
|
### `get(string $key, ...$args)`
|
|
|
|
Obtiene el valor de un setting.
|
|
|
|
```php
|
|
$ttl = settings()->get('cache.ttl');
|
|
```
|
|
|
|
### `set(string $key, mixed $value, ?int $userId = null)`
|
|
|
|
Guarda o actualiza un setting.
|
|
|
|
```php
|
|
settings()->set('menu.visible', true);
|
|
```
|
|
|
|
### `currentNamespace()`
|
|
|
|
Devuelve el namespace actual del contexto.
|
|
|
|
### `listGroups()`
|
|
|
|
Devuelve una colección de todos los grupos de configuración disponibles en el componente.
|
|
|
|
---
|
|
|
|
## 🚀 Comportamiento Avanzado
|
|
|
|
### ❄️ Cache Automática
|
|
|
|
* Al consultar un setting se usa el `KonekoCacheManager` de fondo si está habilitado.
|
|
* Puedes controlar el TTL y activación por:
|
|
|
|
```php
|
|
koneko.cache.enabled
|
|
koneko.admin.cache.ttl
|
|
koneko.admin.avatar.cache.enabled
|
|
```
|
|
|
|
### ⚖️ Tipos automáticos
|
|
|
|
* Si el valor del setting es JSON, se decodifica automáticamente.
|
|
|
|
### 🔨 Almacenamiento estructurado
|
|
|
|
Los datos se almacenan en la base de datos en la tabla `settings`:
|
|
|
|
* `namespace`
|
|
* `key`
|
|
* `value`
|
|
* `user_id`
|
|
|
|
---
|
|
|
|
## 🔧 Casos de Uso Comunes
|
|
|
|
```php
|
|
// 1. TTL de avatar (modo simple)
|
|
$ttl = settings()->in('admin.avatar')->get('cache.ttl');
|
|
|
|
// 2. Cambiar visibilidad del menú del website
|
|
settings()->in('website.menu')->set('visible', true);
|
|
|
|
// 3. Desde un componente que ya registró su namespace:
|
|
settings()->get('enabled');
|
|
|
|
// 4. En test con namespace explícito:
|
|
settings()->in('admin.seo')->set('json_ld.enabled', true);
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ Recomendaciones
|
|
|
|
* Nunca accedas directamente a `KonekoSettingManager`
|
|
* Usa `settings()` siempre que necesites configuración
|
|
* El namespace se debe registrar automáticamente con `KonekoComponentContextRegistrar`
|
|
* Puedes definir valores por `.env` o `config()` que serán sobreescritos si existen en la base de datos
|
|
|
|
---
|
|
|
|
## 🚩 Diagnóstico Rápido
|
|
|
|
```php
|
|
settings()->in('website.menu')->get('debug');
|
|
settings()->in('admin.avatar')->currentNamespace();
|
|
```
|
|
|
|
---
|
|
|
|
## ✨ Integración UI
|
|
|
|
Todos los valores son consultables y modificables desde:
|
|
|
|
* Panel de administrador
|
|
* Vistas Livewire
|
|
* Componentes Vue o Blade mediante API
|
|
|
|
---
|
|
|
|
## 🙏 Agradecimientos
|
|
|
|
Sistema inspirado por la necesidad de centralizar configuraciones por módulo en entornos escalables y cacheables. Diseñado con amor para el ERP Koneko Vuexy Admin México.
|
|
|
|
---
|
|
|
|
\#❤️ ¿Aportaciones?
|
|
Si tienes sugerencias, no dudes en compartirlas en el repositorio oficial Koneko.
|