laravel-vuexy-admin/docs/Helpers/settings-helper-guide.md

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:

settings()->get('clave');
settings()->set('clave', 'valor');

---

⚖️ Jerarquía de Namespace (Prioridad de Resolución)

componentNamespace (ej: admin, website)
    └️ module_slug (ej: avatar, seo, menu)
        └️ key

Ejemplo real:

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.

settings()->self()->get('cache.ttl');

in(string $namespace)

Permite establecer un namespace manual.

settings()->in('admin.avatar')->get('enabled');

get(string $key, ...$args)

Obtiene el valor de un setting.

$ttl = settings()->get('cache.ttl');

set(string $key, mixed $value, ?int $userId = null)

Guarda o actualiza un setting.

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:

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

// 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

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.