# Referencia de API

Referencia completa para funciones y clases del SLM Framework.

## Gestión de Sesiones (Clase `_SLM`)

### `_SLM::auth(): bool`
Verifica si el usuario está autenticado.

```php
if (_SLM::auth()) {
    // El usuario está conectado
}
```

### `_SLM::logout(string $location = './?login'): void`
Cierra sesión del usuario y redirige.

```php
_SLM::logout();                    // Redirige a login
_SLM::logout('./?v=home.main');    // Redirección personalizada
```

### `_SLM::loadSession(): void`
Carga la sesión desde Elasticsearch. Se llama automáticamente en el punto de entrada.

### `_SLM::saveSession(): void`
Guarda la sesión en Elasticsearch. Se llama automáticamente al final del script.

### `_SLM::die(string $status = null): void`
Guarda la sesión y termina el script.

```php
_SLM::die();                       // Solo salir
_SLM::die(json_encode($response)); // Salir con salida
```

### `_SLM::getUserACL(): ?array`
Obtiene la lista de control de acceso del usuario actual.

```php
$acl = _SLM::getUserACL();
```

### `_SLM::getSecurityAccess(string $view, array $acl = null): array`
Obtiene permisos para una vista específica.

```php
$permissions = _SLM::getSecurityAccess('example.items');
// Retorna: ['read', 'create', 'update', 'delete']
```

### `_SLM::switchSession(string $user_id): array`
Cambia a la sesión de otro usuario (función de admin).

```php
$result = _SLM::switchSession($targetUserId);
```

### Datos de Sesión

```php
// Acceder a datos de sesión
$userId = _SLM::$session['user']['id'];
$email = _SLM::$session['user']['email'];
$profile = _SLM::$session['user']['profile'];
$acl = _SLM::$session['user']['profile']['acl'];
```

---

## Helpers de Respuesta

### `_response(bool $error, string|array|null $message = null, array $data = null): array`
Crea un array de respuesta estandarizado.

```php
// Error
_response(true, 'Mensaje de error');

// Éxito
_response(false, 'Mensaje de éxito');

// Éxito con datos
_response(false, '', ['id' => $newId]);

// Múltiples campos de datos
_response(false, 'Creado', ['id' => $id, 'closeModal' => true]);
```

### `jsonResponse(array $response): never`
Envía JSON como respuesta y termina.

```php
jsonResponse(_response(false, 'OK'));
```

### `jsonError(string $message, array $data = null): never`
Envía JSON de error y termina.

```php
jsonError('Validación fallida');
```

### `jsonSuccess(string $message = '', array $data = null): never`
Envía JSON de éxito y termina.

```php
jsonSuccess('Elemento creado', ['id' => $id]);
```

---

## Helpers de Validación

### `validateRequiredFields(array $fields, array $source = null): void`
Valida que los campos requeridos estén presentes.

```php
validateRequiredFields(['name', 'email']);
validateRequiredFields(['name'], $customArray);
```

### `validateEmail(string $email): string`
Valida y sanitiza email.

```php
$email = validateEmail($_POST['email']);
```

### `validateInt(mixed $value, int $min = 0, int $max = PHP_INT_MAX, int $default = 0): int`
Valida entero en rango.

```php
$page = validateInt($_POST['page'], 1, 100, 1);
```

### `validateBool(mixed $value): bool`
Convierte valor a booleano.

```php
$active = validateBool($_POST['active']);
```

### `escapeEsValue(string $value): string`
Escapa valor para consultas Elasticsearch.

```php
$safe = escapeEsValue($_POST['search']);
```

---

## Helpers de Valores POST

### `getPostValue(string $key, mixed $default = ''): mixed`
Obtiene cualquier valor de POST.

```php
$value = getPostValue('field', 'default');
```

### `getPostString(string $key, string $default = ''): string`
Obtiene string recortado de POST.

```php
$name = getPostString('name');
```

### `getPostInt(string $key, int $default = 0): int`
Obtiene entero de POST.

```php
$page = getPostInt('page', 1);
```

### `getPostBool(string $key, bool $default = false): bool`
Obtiene booleano de POST.

```php
$active = getPostBool('active', false);
```

---

## Funciones de Elasticsearch

### `getEsServer(): string`
Obtiene URL del servidor ES según el entorno.

### `getEsIndex(): string`
Obtiene nombre del índice principal según el entorno.

### `getEsIndexLog(): string`
Obtiene nombre del índice de logs según el entorno.

### `es_execute(string $url, string $json = "", string $verb = ""): bool|string`
Ejecuta solicitud a Elasticsearch.

```php
// Solicitud GET
$result = es_execute("/mi-indice/_doc/123");

// POST con cuerpo JSON
$result = es_execute("/mi-indice/_doc", $jsonData, "POST");

// DELETE
$result = es_execute("/mi-indice/_doc/123", "", "DELETE");
```

### `setNewObject(array $data, string $id = "", string $es_index = ""): array`
Crea nuevo documento.

```php
$data = [
    'name' => 'Elemento',
    'slm' => ['type' => 'item', 'timestamp' => getTimestamp()]
];
$result = setNewObject($data);
$newId = $result['_id'];
```

### `updateObjectByID(string $id, array $data, string $es_index = ""): array`
Actualiza documento por ID.

```php
$result = updateObjectByID($id, ['name' => 'Nuevo Nombre']);
```

### `getObjectById(string $id, string $ext = "", string $es_index = ""): false|array`
Obtiene documento por ID.

```php
$item = getObjectById($id);
$user = getObjectById($id, '_source_excludes=password');
```

### `getObjectWithValue(string $type, string $field, string $value, string $es_index = ""): array`
Encuentra documento por valor de campo.

```php
$user = getObjectWithValue('user', 'email.keyword', 'usuario@ejemplo.com');
```

### `getTimestamp(): float`
Obtiene marca de tiempo actual en milisegundos.

```php
$timestamp = getTimestamp(); // 1704067200000
```

---

## Helpers de Enrutamiento

### `getApi(string $url, string $path = "../slm.framework/modules"): string`
Obtiene ruta al archivo slm_api.slm del módulo.

```php
$path = getApi('users.list'); // ../slm.framework/modules/users/slm_api.slm
```

### `getAction(string $url, string $pre, string $path = "../slm.framework/modules"): string`
Obtiene ruta al archivo de acción.

```php
$path = getAction('users.list', 'view'); // ../slm.framework/modules/users/view.list.slm
$path = getAction('users.list', 'ajax'); // ../slm.framework/modules/users/ajax.list.slm
```

---

## Funciones de Entorno

### `isProd(): bool`
Verifica si está corriendo en producción.

```php
if (isProd()) {
    // Entorno de producción
}
```

### `isDev(): bool`
Verifica si está corriendo en desarrollo.

```php
if (isDev()) {
    error_log('Info de debug...');
}
```

---

## Logging

### `addToLog(string $type, string $module, string $script, array $data, array $debug = [], array $log = []): array`
Agrega entrada al índice de logs.

```php
addToLog('success', 'users', 'createUser', ['userId' => $id]);
addToLog('error', 'users', 'createUser', ['message' => $e->getMessage()]);
addToLog('warning', 'security', 'login', ['email' => $email]);
```

Tipos de log: `success`, `error`, `warning`

---

## Funciones de Utilidad

### `generateRandomString(int $length = 12): string`
Genera string alfanumérico aleatorio.

```php
$code = generateRandomString(6);  // "aB3xY9"
$token = generateRandomString(32);
```

### `convertHumanDateToMilliseconds(string $date, string $format = ''): float`
Convierte string de fecha a timestamp.

```php
$ms = convertHumanDateToMilliseconds('2024-01-01');
$ms = convertHumanDateToMilliseconds('01/01/2024', 'Y-m-d');
```

### `createDirectoryIfNotExists(string $path, int $permissions = 0775): void`
Crea directorio si no existe.

```php
createDirectoryIfNotExists('../store/uploads');
```

### `toSnakeCase(string $string): string`
Convierte string a snake_case.

```php
$snake = toSnakeCase('Hola Mundo'); // "hola_mundo"
```

### `sanitizeString(string $value, string $case = ''): string`
Recorta y opcionalmente cambia mayúsculas/minúsculas.

```php
$name = sanitizeString($_POST['name']);
$upper = sanitizeString($_POST['code'], 'upper');
$lower = sanitizeString($_POST['email'], 'lower');
```

---

## Funciones de Email

### `createMailer(): PHPMailer`
Crea instancia de PHPMailer configurada.

### `sendToken(string $email, array $data, bool $debug = false): bool`
Envía email con token de seguridad.

```php
$sent = sendToken($email, [
    'token' => $code,
    'fecha_creacion' => $created,
    'fecha_expiracion' => $expires
]);
```

---

## Clase SSP (DataTables)

```php
$ssp = new SSP($searchTerm, $searchConditions, $searchFields, $params);
$result = $ssp
    ->setEsIndex(getEsIndex())
    ->setDefaultOperator('AND')
    ->setDebug(true)
    ->setReturn(true)
    ->run();

// Estructura del resultado:
[
    'recordsTotal' => 100,
    'recordsFiltered' => 50,
    'data' => [...],
    'query' => '...' // Solo si debug=true
]
```

---

## Clase SSPBootstrapTable

```php
$ssp = new SSPBootstrapTable($searchTerm, $search, $fields, $params);
$result = $ssp->setEsIndex(getEsIndex())->setReturn(true)->run();

// Estructura del resultado:
[
    'total' => 100,
    'rows' => [...]
]
```

---

## Clase Curl

```php
$curl = new Curl('https://api.ejemplo.com/data');
$response = $curl
    ->setHeaders(['Authorization: Bearer token'])
    ->setParameters(['page' => 1])
    ->verificarSsl(false)
    ->get();

// Solicitud POST
$curl = new Curl('https://api.ejemplo.com/create');
$response = $curl
    ->setHeaders(['Content-Type: application/json'])
    ->setJsonPost(['name' => 'Test'])
    ->get();

$statusCode = $curl->getStatusCode();
```

---

## Clase CryptDecryptData

```php
$crypto = new CryptDecryptData($key, 'AES-256-CBC', $iv);
$encrypted = $crypto->encrypt('datos sensibles');
$decrypted = $crypto->decrypt($encrypted);
```

---

## Encriptación Global

```php
// Establecer clave (se hace automáticamente para usuarios autenticados)
setSecretKey($key);

// Encriptar
$encrypted = encrypt('datos');

// Desencriptar
$decrypted = decrypt($encrypted);
```
