# Documentación de Histrix
> Documentación técnica del framework Histrix, desarrollado por Mundo IT.
Este archivo reúne la documentación completa de https://docs.histrix.com.ar/ en un solo texto plano,
para usarla como contexto en un asistente de AI. Cada página incluye su URL: citala
al responder para que se pueda verificar la fuente.
Generado el 2026-08-28 · 35 páginas.
==============================================================================
# Introducción
==============================================================================
------------------------------------------------------------------------------
## Qué es Histrix
URL: https://docs.histrix.com.ar/es/introduccion/
Descripción general del framework, sus capacidades y su modelo de trabajo.
------------------------------------------------------------------------------
Histrix es un framework para construir aplicaciones de gestión de información. Las
pantallas —consultas, fichas, formularios de ingreso, árboles, gráficos, calendarios—
se declaran en archivos XML que el motor interpreta en cada request: no hay
compilación ni build previo, y un cambio en un XML se refleja al recargar la página.
Sobre esa base se desarrollan módulos por dominio (clientes, proveedores, stock,
contabilidad, tesorería, entre otros) y se los configura por cliente sin duplicar el
motor.
## Modelo de trabajo
- **Definición declarativa.** Un XML describe la tabla base, los campos, los joins,
los filtros y el comportamiento de grabación. El motor genera el SQL, renderiza la
interfaz y expone la misma definición por API REST.
- **Extensión en PHP cuando hace falta.** El atributo `dataSource` reemplaza la
generación automática de SQL por una clase propia. Ver
[DataSource en PHP](https://docs.histrix.com.ar/es/datasource/).
- **Multi-base.** Una misma instalación atiende varias bases de datos, cada una con su
configuración, sus XML propios y su módulo base. Los XML de la base sobrescriben por
completo los del módulo.
## Orígenes de datos
- Bases de datos propias o de terceros: MySQL/MariaDB, SQL Server, Progress y SQLite.
- Dispositivos: relojes de personal, centrales telefónicas, controladores PLC,
sensores.
- Servicios web: cotizaciones, listas de precios, organismos públicos.
## Interfaces de acceso
Histrix funciona en el navegador y no requiere instalar software en las terminales.
Además de la interfaz web, expone una **API REST** que publica los mismos XML como
recursos, con autenticación OAuth 2.0 y OpenID Connect. Eso permite construir
clientes alternativos —móviles o SPA— sobre la misma definición. Ver
[Referencia de la API](https://docs.histrix.com.ar/es/api/) y
[Autenticación y OIDC](https://docs.histrix.com.ar/es/autenticacion/).
## Formatos de salida
Los datos de cualquier consulta pueden exportarse a XLS, CSV, PDF, XML y RSS, y los
listados imprimirse en PDF o en impresoras térmicas. Ver
[Exportación de datos](https://docs.histrix.com.ar/es/exportar/).
## Licenciamiento
Histrix no impone límite de usuarios ni licencias por terminal, y está construido
íntegramente sobre software libre: no requiere licencias de sistema operativo ni de
motor de base de datos.
------------------------------------------------------------------------------
## Arquitectura
URL: https://docs.histrix.com.ar/es/arquitectura/
Estructura de una instalación, resolución de XML por base, overrides de módulo y ciclo de vida de una instancia.
------------------------------------------------------------------------------
Esta página describe cómo está organizada una instalación de Histrix y cómo el motor
resuelve qué XML ejecutar. Es la base para entender por qué un mismo programa puede
comportarse distinto en dos bases de la misma instalación.
## Estructura de directorios
Una instalación tiene el motor en la raíz y los datos de cada cliente separados en
`database/`:
```
histrix/
src/ Motor (namespace \Histrix\)
admin/ Programas de administración y migraciones del core
modules/ Módulos funcionales compartidos (erp-base, erp-full, ...)
plugins/ Plugins del core
lang/ Traducciones de la interfaz (es, en, fr, pt)
js/ css/ Assets del cliente web
database/
config.xml Configuración de conexiones y empresas
{cliente}/
xml/ XML propios del cliente (sobrescriben los del módulo)
files/ Archivos subidos
log/{año}/{mes}/ Logs de SQL y errores
plugins/ Plugins propios del cliente
tests/ Tests de aceptación de la base
vendor/ Dependencias de Composer
```
`database/` y `modules/` son repositorios independientes del motor. Un cambio en un
módulo o en los XML de un cliente no se versiona junto con el core.
## Configuración de conexiones
`database/config.xml` declara una entrada `` por cada base atendida. El atributo
`xmlPath` define el directorio raíz de sus XML, es decir `database/{xmlPath}/xml/`:
```xml
histrix_back.jpg
es
Cliente S.A.
htx_cliente
mysql
usuario
clave
db
Cliente S.A.
Dirección
30-00000000-0
logo.jpg
logo.png
|clientes|proveedores|stock|iva|contabilidad
```
El atributo opcional `group` en `` filtra qué bases aparecen en el selector
según el subdominio por el que se accede.
## Resolución de XML
Cada base tiene además un parámetro `CONFIG::baseModule` en la tabla `HTXOPTIONS`
(por ejemplo `erp-base` o `erp-full`) que define contra qué módulo hace fallback. Al
pedir un XML, el motor prueba las rutas en este orden y toma la primera que existe:
1. `database/{xmlPath}/xml/{dir}/{archivo}`
2. `database/{xmlPath}/xml/{archivo}`
3. `modules/{baseModule}/{dir}/{archivo}`
4. `modules/{dir}/{archivo}`
5. `admin/{dir}/{archivo}`
6. `modules/erp-base/{dir}/{archivo}`
Consecuencias prácticas:
- Un XML colocado en la raíz del árbol del cliente (paso 2) satisface cualquier
`dir=`, porque ese paso ignora el subdirectorio.
- Si el `xmlPath` de una base apunta a un directorio vacío, todo se resuelve por
fallback al módulo.
- Dos bases con `baseModule` distinto pueden cargar versiones diferentes del mismo
archivo. Si un programa se comporta distinto entre bases del mismo motor, comparar
primero `CONFIG::baseModule` y el contenido de cada `xmlPath`.
## Overrides de módulo
Un XML en `database/{cliente}/xml/` **reemplaza por completo** al del módulo: no hay
merge parcial de campos ni de atributos. Por lo tanto:
- Antes de modificar un override, compararlo con `diff` contra el original del módulo.
Un override desactualizado se rompe en silencio cuando el archivo del módulo
evoluciona.
- Al crear un override, dejar registrado qué se cambió respecto del original.
## Ciclo de vida de una instancia
Cuando se abre un programa, el motor parsea el XML y construye un **contenedor**
(`\Histrix\Data\Container`) con las tablas, campos y condiciones declaradas. Ese
contenedor se serializa en la sesión y queda identificado por un id de instancia,
que es el que usan todas las operaciones siguientes:
```
GET /api/db/{db}/instance/xml/{ruta.xml} crea la instancia
GET /api/db/{db}/instance/{instance} lee datos
PUT /api/db/{db}/instance/{instance}/set/ actualiza un campo
POST /api/db/{db}/instance/{instance}/process/ graba
DELETE /api/db/{db}/instance/{instance} destruye la instancia
```
El estado vive en la sesión de PHP, no en el cliente: los campos calculados en el
servidor, los valores de los filtros y las filas confirmadas de una grilla de ingreso
se resuelven contra esa instancia. La interfaz web y cualquier cliente externo usan
las mismas rutas.
## Stack
- PHP 8 con Slim 3 para el enrutamiento HTTP y Composer para las dependencias.
- Acceso a datos por PDO. El tag `` de cada base selecciona la implementación:
`mysql` (valor por omisión), `mssql`, `dblib` o `sqlsrv` para SQL Server, `progress` y
`sqlite`.
- OAuth 2.0 y OpenID Connect para autenticación de la API.
- Redis como caché de aplicación y almacenamiento de las filas temporales de los
formularios de ingreso.
- jQuery, jQuery UI y DataTables en el cliente web.
El servidor Redis se resuelve, en este orden, desde los tags `` y
`` de la base en `config.xml`, desde las variables de entorno
`REDIS_SERVER_HOST` y `REDIS_SERVER_PASSWORD`, o por defecto `localhost`.
:::note
Las sesiones de PHP **no** se guardan en Redis: usan el manejador de archivos
predeterminado. El bloqueo de sesión que eso implica es intencional, porque hay flujos
—los popups de `` con `resume="true"`— que dependen de que las escrituras a
la sesión estén serializadas.
:::
==============================================================================
# Instalación y operación
==============================================================================
------------------------------------------------------------------------------
## Instalación con Nginx y Docker
URL: https://docs.histrix.com.ar/es/instalacion_nginx/
Instalación de Histrix con Nginx, PHP-FPM, MySQL y Redis usando Docker Compose.
------------------------------------------------------------------------------
Este documento describe la instalación de Histrix con Nginx y MySQL usando Docker y
Docker Compose. Es el procedimiento recomendado para instalaciones nuevas.
## Primeros pasos
### Instalación de Docker
Para instalar Docker puedes seguir los pasos de la [documentación oficial](https://docs.docker.com/engine/install/).
En este caso, se instalará Docker en Ubuntu 24.04 usando apt.
```bash
# Actualizar el índice de paquetes:
sudo apt-get update
# Instalar paquetes para permitir a apt usar un repositorio sobre HTTPS:
sudo apt-get install ca-certificates curl
# Agregar la clave GPG oficial de Docker:
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Agregar el repositorio de Docker a las fuentes de APT:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
# Instalar Docker:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Verificar la instalación:
sudo docker --version
```
### Rotación de logs de los contenedores
Sin límite de tamaño, los logs de los contenedores crecen hasta llenar el disco del
servidor. El límite se declara **en el `docker-compose.yml`**, en cada servicio, y así
queda versionado junto con el resto de la definición:
```yaml
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
```
Con eso cada contenedor guarda como máximo 5 archivos de 10 MB. El archivo completo del
apartado [Docker Compose de Histrix](https://docs.histrix.com.ar/es/instalacion_nginx/#docker-compose-de-histrix) ya lo trae aplicado a
los tres servicios mediante un bloque reutilizable.
:::caution
Poner `log-driver` y `log-opts` en `/etc/docker/daemon.json` no alcanza. Ese archivo fija
únicamente el valor por omisión del daemon: solo afecta a los contenedores **creados
después** del cambio —los que ya existen conservan su configuración aunque se reinicien—
y cualquier bloque `logging` del compose lo sobrescribe. Declararlo en el compose es lo
que efectivamente limita el tamaño.
:::
:::tip
Para más información sobre el driver de logs, consultar la
[documentación oficial](https://docs.docker.com/engine/logging/drivers/json-file/).
:::
## Configurar usuario del servicio
Como usario root, crear un usuario para el servicio de Histrix:
```bash
sudo adduser automata
```
le damos permisos de sudo:
```bash
sudo usermod -aG sudo automata
```
Le damos permisos de docker:
```bash
sudo usermod -aG docker automata
```
## Instalación de Histrix
Para inicar tiene que entrar como usuario automata:
```bash
su - automata
```
Dentro del home del usuario automata tienes que generar la siguiente estructura de carpetas:
```bash
mkdir -p ~/[Nombre del cliente]/{modules,database}
```
Para continuar tienes que crear una api key de bitbucket con permisos de lectura y escritura de repositorios. En el siguiente [enlace](https://bitbucket.org/account/settings/app-passwords/) puedes crear una api key.
Teniendo la api key te mueves a la carpeta modules y clonas los modulos de histrix:
```bash
cd ~/[Nombre del cliente]/modules
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/erp-full.git erp-full
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/htxcore.git histrix
```
En la carpeta database tienes que clonar el repositorio de los xmls del cliente:
```bash
cd ~/[Nombre del cliente]/database
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/[nombre-repositorio-xml].git
```
## Configuración de Histrix
Histrix su configuracion va en la carpeta database con un archivo llamado config.xml que tiene la siguiente estructura:
```xml
histrix_back.jpg
es
[Nombre del ciente]
[nombre de la base de dato]
mysql
[Usuario de la base de dato]
[Contraseña de la base de dato]
[url del servidor base de dato]
[Nombre del ciente]
[Direccion del ciente]
[Cuit del cliente]
logo.jpg
logo.png
|clientes|proveedores|stock|iva|contabilidad|packs|vendedores|transportistas
```
El atributo `xmlPath` de cada `` define el directorio de sus XML
(`database/{xmlPath}/xml/`) y, junto con el parámetro `CONFIG::baseModule` de la tabla
`HTXOPTIONS`, determina cómo se resuelve cada archivo. Ver
[Arquitectura](https://docs.histrix.com.ar/es/arquitectura/).
:::caution[Actualización de una instalación anterior a mayo de 2026]
Migrar una instalación previa exige dos cambios de schema que no se pueden aplicar desde
la interfaz:
- `HTXPROFILES.realm` — sin esa columna el login devuelve 500 para todos los usuarios,
incluido el administrador.
- `HTXMENU.web_version = 1` — sin ese valor el menú aparece vacío y sin ningún error.
Con el sistema de migraciones instalado, ambos cambios se aplican con
`php histrix migrate --all-databases`. Ver
[Migraciones de base](https://docs.histrix.com.ar/es/migraciones/).
:::
## Docker Compose de Histrix
Se crea un archivo `docker-compose.yml` en la raíz del usuario `automata` con el
siguiente contenido:
```yaml
# Política de logs compartida por los tres servicios
x-logging: &default-logging
driver: json-file
options:
max-size: "10m"
max-file: "5"
services:
redis:
image: redis:6.0.3-buster
restart: unless-stopped
container_name: redis
logging: *default-logging
expose:
- "6379"
command: "redis-server --appendonly yes"
networks:
- backend
db:
image: mysql:8.3.0
command: --default-authentication-plugin=mysql_native_password --sql-mode="NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"
container_name: db
volumes:
- mysql-data:/var/lib/mysql
restart: unless-stopped
logging: *default-logging
networks:
- backend
expose:
- "3306"
environment:
MYSQL_ROOT_PASSWORD: [Contraseña de la base de dato]
MYSQL_ROOT_HOST: '%'
MYSQL_DATABASE: [nombre de la base de dato]
TZ: America/Argentina/Buenos_Aires
php:
image: mundoit/histrix-runtime:nginx-06
restart: unless-stopped
container_name: histrix
logging: *default-logging
volumes:
- "/home/automata/[nombre-cliente]/database:/var/www/html/database"
- "/home/automata/[nombre-cliente]/modules:/var/www/html/modules"
ports:
- "80:80"
# Solo si se va a usar el servidor de notificaciones:
# - "8888:8888"
depends_on:
- redis
- db
environment:
- REDIS_SERVER_HOST=redis
- GIT_EMAIL=[Correo electronico del usuario de bitbucket]
- GIT_NAME=[Nombre del usuario de bitbucket]
- GIT_PERSONAL_TOKEN=[Api key de bitbucket]
- GIT_USERNAME=[Nombre de usuario de bitbucket]
- GIT_REPO=bitbucket.org/mundo-it/histrix.git
- GIT_BRANCH=nginx-fpm
- PGID=[ID del grupo de automata]
- PUID=[ID del usuario de automata]
- WEBROOT=/var/www/html
- RUN_SCRIPTS=1
- PHP_MEM_LIMIT=1024M
- PHP_POST_MAX_SIZE=1024M
- PHP_UPLOAD_MAX_FILESIZE=1024M
- PHP_ERRORS_STDERR=1
- SKIP_COMPOSER=1
- REMOVE_FILES=0
- ERRORS=0
networks:
- backend
- frontend
links:
- db
volumes:
mysql-data: # Donde se guarda la base de datos
networks:
backend:
frontend:
```
:::note
El compose necesita el ID del usuario y del grupo de `automata`:
```bash
id automata
# Salida
# uid=1000(automata) gid=1000(automata) groups=1000(automata),27(sudo),100(users),987(docker)
```
:::
### Puerto 8888
El 8888 es el puerto del servidor de notificaciones por WebSocket. **Solo hay que
exponerlo si se va a levantar el push server**; en una instalación que no usa
notificaciones en tiempo real, publicarlo no aporta nada y amplía la superficie expuesta.
Ver [Servidor de notificaciones](https://docs.histrix.com.ar/es/pushserver/).
## Iniciar Histrix
```bash
docker compose up -d
```
Histrix queda escuchando en el puerto 80 de la máquina.
:::caution
Los cambios de `logging` en el compose se aplican al **crear** el contenedor, no al
reiniciarlo. En una instalación que ya está corriendo hay que recrear los contenedores:
```bash
docker compose up -d --force-recreate
```
Para verificar que quedó aplicado:
```bash
docker inspect -f '{{.HostConfig.LogConfig}}' histrix
```
:::
:::tip
Para más información sobre Docker Compose, consultar la
[documentación oficial](https://docs.docker.com/compose/).
:::
## Comandos útiles
### Pull de cambios de Histrix
Para hacer un pull de los cambios de Histrix, se debe ejecutar el siguiente comando:
```bash
sudo docker exec -t -i histrix /usr/bin/pull
```
### Pull de cambios de los modulos
Para hacer un pull de los cambios de los modulos de Histrix, se debe ejecutar el siguiente comando:
```bash
cd ~/[Nombre del cliente]/modules/erp-full
git pull
cd ~/[Nombre del cliente]/modules/histrix
git pull
```
### Pull de cambios de los xmls
Para hacer un pull de los cambios de los xmls del cliente, se debe ejecutar el siguiente comando:
```bash
cd ~/[Nombre del cliente]/database/[nombre-repositorio-xml]
git pull
```
### Ver logs de Histrix
Los logs se organizan por año y mes dentro del directorio de la base:
```bash
cd ~/[Nombre del cliente]/database/[nombre-repositorio-xml]/log/[año]/[mes]
# Consultas
tail -f sql_select.log
# Inserciones y actualizaciones
tail -f sql_update.log
```
El directorio del mes se crea al vuelo, así que necesita permiso de escritura para el
proceso de PHP. Ver [Problemas frecuentes](https://docs.histrix.com.ar/es/problemasfrecuentes/).
### Regenerar el mapa de clases
Necesario después de crear, mover o renombrar una clase de `dataSource`:
```bash
docker exec -it histrix composer dumpautoload
```
### Aplicar migraciones
```bash
docker exec -it histrix php histrix migrate:status --all-databases
docker exec -it histrix php histrix migrate --all-databases
```
### Limpiar el caché de assets
Cuando los bundles de JavaScript o CSS quedan con contenido inválido:
```bash
docker exec histrix sh -c 'rm -rf /tmp/histrix/*'
```
Los cambios en los XML no requieren limpiar nada: el motor los reparsea en cada request y
se ven recargando la página.
### Correr los tests
```bash
docker exec -it histrix vendor/bin/phpunit
```
------------------------------------------------------------------------------
## Instalación con Apache
URL: https://docs.histrix.com.ar/es/instalacion/
Instalación de Histrix con Apache y MySQL sobre un servidor Ubuntu físico o virtual.
Estado: Histórico.
------------------------------------------------------------------------------
:::caution[Documento histórico]
Este procedimiento corresponde a instalaciones sobre Apache sin contenedores. Se conserva
como referencia para las instalaciones existentes. Para una instalación nueva, seguir
[Instalación con Nginx y Docker](https://docs.histrix.com.ar/es/instalacion_nginx/).
:::
### Instalación automática
~~~bash
sudo apt-get install git
git clone https://bitbucket.org/mundo-it/histrix_installer.git
cd histrix_installer
sudo ./setup.sh
~~~
### Paquetes necesarios
#### Ubuntu
Paquetes indispensables para el funcionamiento de Histrix.
#### MySQL
~~~bash
sudo apt-get install mysql-server
~~~
#### PHP
~~~bash
sudo apt-get install php php-common php-mysql php-gd php-imagick php-xmlrpc
~~~
#### Redis
~~~bash
sudo apt-get install redis-server php-redis
~~~
### Recomendados
Optimiza el rendimiento de PHP al precompilar los programas
~~~bash
sudo apt-get install php-xcache
~~~
### Opcionales
Ldap, permite sincronizar tablas del sistema con servidores ldap.
~~~bash
sudo apt-get install php-ldap
~~~
Imap permite que histrix pueda ser configurado para chequear casillas de correo externas.
~~~bash
sudo apt-get install php-imap
~~~
Para soporte con bases de datos MS sql server
~~~bash
sudo apt-get install php-sybase
~~~
Soporte para visualizar PDF con Flash on line
Estos paquetes permiten visualizar archivos pdf con el visualizador interno en flash
~~~bash
sudo add-apt-repository ppa:guilhem-fr/swftools
sudo apt-get update
sudo apt-get install swftools
~~~
### Clonado de un repositorio
Por defecto el path de instalación de histrix es en /usr/share por tal motivo haremos los siguientes pasos
~~~bash
cd /usr/share
sudo git clone https://bitbucket.org/mundo-it/histrix.git
~~~
### Archivo de Configuración
**Ejemplo de Archivo de Configuración Apache**
~~~xml
ServerAdmin info@tld.com
DocumentRoot [path_histrix]
Options -Indexes FollowSymLinks -MultiViews
IndexIgnore *
AllowOverride All
Order allow,deny
Allow from all
ErrorLog /var/log/apache2/error.log
LogLevel error
CustomLog /var/log/apache2/access.log combined
#SSLEngine On
#SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
#SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
SetOutputFilter DEFLATE
SetEnvIfNoCase Request_URI \.(?:exe|t?gz|jpg|zip|bz2|sit|rar)$ no-gzip dont-vary
# Keep a log of compression ratio on each request
DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio
LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog /var/log/apache2/htxdeflate.log deflate
BrowserMatch ^Mozilla/4 gzip-only-text/html
BrowserMatch ^Mozilla/4\.0[678] no-gzip
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
~~~
Si Se quiere forzar la utilización de SSL, se puede introducir la siguiente configuración para que todas las peticiones http se traduzcan en https
~~~bash
RewriteEngine on
RewriteCond %{SERVER_PORT} ^80$
RewriteRule ^(.*)$ https://%{SERVER_NAME}$1 [L,R]
~~~
Histrix utiliza un archivo de configuración config.xml, el mismo debe colocarse en la carpeta config de la instalación local
**Ejemplo de Archivo de Configuración**
~~~xml
NOMBRE DE LA EMPRESA S.R.L.
es
database/empresa/img/logo_inicio.jpg
../database/empresa/img/fondo_empresa.jpg
empresadb
mysql
database_user
Database_password
localhost
EMPRESA
EMPRESA
Calle Nro xxx
9999999
clientes proveedores stock vendedores
custom.css
logo_empresa.jpg
logo2.jpg
logo_empresa.jpg
fondo_empresa.jpg
clientes proveedores stock vendedores transportistas
es
http://www.estudiogenus.com
imap.gmail.com
info@domain.com.ar
smtp.gmail.com
mail@domain.com.ar
password_email
~~~
**Sistema de Archivos**
Histrix soporta montar sistemas de archivos locales o remotos tanto para los modulos XML como para los archivos adjuntos, dentro del tag \:
~~~xml
id="files" Para arhivos Adjuntos
id="xml" Para modulos Xml
~~~
Ejemplos para diversos adaptadores:
**Local**
~~~xml
[PATH]
~~~
**AWS**
~~~xml
[ACESS_KEY]
[SECRET]
[REGION]
[AWS_OPTIONAL_PATH]
[AWS_BUCKET]
~~~
**Dropbox**
Para configurar Dropbox: .
~~~xml
[ACESS_KEY]
[ACCESS_TOKEN]
[SECRET]
[OPTIONAL_PATH]
~~~
**Rackspace**
~~~xml
[USERNAME]
[PASSWORD]
[CONTAINER]
[OPTIONAL_PATH]
~~~
------------------------------------------------------------------------------
## Comandos del CLI
URL: https://docs.histrix.com.ar/es/cli/
Script de administración y mantenimiento de una instalación de Histrix.
------------------------------------------------------------------------------
El script `histrix` en la raíz de la instalación agrupa las tareas de administración:
alta de bases, instalación y actualización de módulos, migraciones, servidor de
notificaciones, tareas programadas y ejecución de tests.
```bash
cd /usr/share/histrix
php histrix
```
Sin argumentos imprime la ayuda con todos los comandos disponibles.
:::note
En una instalación con Docker el script se ejecuta dentro del contenedor:
```bash
docker exec -it histrix php histrix migrate:status --all-databases
```
:::
## Bases y módulos
| Comando | Descripción |
| --- | --- |
| `histrix new [base] [usuario] [clave] [host]` | Crea una base nueva con su estructura de directorios, sus tablas de sistema y su entrada en `config.xml` |
| `histrix list` | Lista los módulos disponibles |
| `histrix install [módulo] [usuario]` | Instala un módulo desde su repositorio |
| `histrix update` | Actualiza el motor y las dependencias de Composer |
| `histrix update [módulo]` | Actualiza un módulo desde su repositorio |
| `histrix update --all-modules` | Actualiza todos los módulos |
`histrix new` deja creado el árbol `database/{base}/` con sus subdirectorios (`xml`,
`files`, `log`, `tests`), crea las tablas de sistema, el menú por omisión y el usuario
inicial de Histrix.
## Migraciones
| Comando | Descripción |
| --- | --- |
| `histrix migrate` | Aplica las migraciones pendientes |
| `histrix migrate:status` | Muestra el estado por módulo |
| `histrix migrate:rollback` | Revierte el último lote |
| `histrix migrate:diff` | Compara el schema real contra el SQL del módulo |
| `histrix migrate:generate` | Crea una migración nueva |
| `histrix migrate:export` | Exporta al módulo tablas y rutinas que solo existen en la base |
Detalle de opciones en [Migraciones de base](https://docs.histrix.com.ar/es/migraciones/).
## Servicios
| Comando | Descripción |
| --- | --- |
| `histrix scheduler [base]` | Dispara el planificador de tareas de una base |
| `histrix push-server [host:puerto] [public.pem] [private.pem]` | Levanta el servidor de notificaciones |
`scheduler` es el comando que se engancha al cron del sistema para ejecutar las tareas
programadas de cada base. Ver
[Servidor de notificaciones](https://docs.histrix.com.ar/es/pushserver/).
## Tests
| Comando | Descripción |
| --- | --- |
| `histrix test [base] [ArchivoCest.php] [entorno]` | Corre los tests de aceptación de una base |
| `histrix xmltest [archivo] [base]` | Corre el test de un XML puntual |
Ver [Testing](https://docs.histrix.com.ar/es/testing/).
------------------------------------------------------------------------------
## Migraciones de base
URL: https://docs.histrix.com.ar/es/migraciones/
Sistema de migraciones versionadas para el schema del core y de los módulos.
------------------------------------------------------------------------------
Los cambios de schema del core y de los módulos se aplican con migraciones
versionadas. No se editan a mano en cada base ni se distribuyen como scripts SQL
sueltos: se escriben una vez, quedan versionadas en el repositorio del módulo y se
aplican en todas las bases con el mismo comando.
## Módulos y ubicaciones
Cada conjunto de migraciones pertenece a un módulo, y el motor los descubre solo:
| Módulo | Directorio de migraciones |
| --- | --- |
| `core` | `admin/migrations/` |
| `erp` | `modules/erp-migrations/` |
| Cualquier otro | `modules/{módulo}/migrations/` |
## Formato de una migración
El nombre del archivo es una marca de tiempo de 14 dígitos, un guion bajo y el nombre
en *snake_case*: `20260611103000_add_realm_to_profiles.php`. También se aceptan
archivos `.sql` con el mismo patrón.
Una migración PHP extiende `AbstractMigration` y define `up()` y `down()`:
```php
addColumn('HTXPROFILES', 'realm', "VARCHAR(255) NOT NULL DEFAULT 'web'");
}
public function down()
{
$this->dropColumn('HTXPROFILES', 'realm');
}
}
```
`AbstractMigration` provee ayudas idempotentes para no romper en bases donde el cambio
ya existe:
| Método | Uso |
| --- | --- |
| `execute($sql)` | Ejecuta SQL literal |
| `query($sql)` | Ejecuta y devuelve el resultado |
| `tableExists($tabla)` | Verifica la existencia de una tabla |
| `columnExists($tabla, $columna)` | Verifica la existencia de una columna |
| `createTable($nombre, $columnas, $opciones)` | `CREATE TABLE IF NOT EXISTS` (InnoDB y utf8mb4 por defecto) |
| `dropTable($nombre)` | Elimina la tabla |
| `addColumn($tabla, $columna, $tipo, $after)` | Agrega la columna solo si falta |
| `dropColumn($tabla, $columna)` | Elimina la columna |
| `renameColumn($tabla, $viejo, $nuevo, $tipo)` | Renombra la columna |
| `addIndex($tabla, $columnas, $nombre, $unique)` | Crea un índice |
| `dropIndex($tabla, $nombre)` | Elimina un índice |
## Comandos
Todos aceptan `--db={base}` para una base puntual o `--all-databases` para recorrer
todas las declaradas en `config.xml`, y `--module={módulo}` para limitar el alcance.
```bash
# Estado de las migraciones
php histrix migrate:status --all-databases
# Aplicar las pendientes (--dry-run muestra sin ejecutar)
php histrix migrate --all-databases
php histrix migrate --db=cliente --module=erp-full --dry-run
# Revertir el último lote (o N lotes con --steps)
php histrix migrate:rollback --db=cliente
php histrix migrate:rollback --db=cliente --steps=3
# Crear una migración vacía
php histrix migrate:generate --module=erp-full "add realm to profiles"
# Comparar el schema real contra el SQL del módulo
php histrix migrate:diff --db=cliente --module=erp-full
php histrix migrate:diff --db=cliente --module=erp-full --generate
# Exportar al módulo las tablas y rutinas que existen en la base pero no en su SQL
php histrix migrate:export --module=erp-full --dry-run
```
Opciones específicas:
| Comando | Opción | Efecto |
| --- | --- | --- |
| `migrate` | `--dry-run` | Muestra lo que haría sin tocar la base |
| `migrate:rollback` | `--steps=N` | Cantidad de lotes a revertir (1 por defecto) |
| `migrate:diff` | `--generate` | Genera una migración con las diferencias encontradas |
| `migrate:diff` | `--force` | Continúa ante diferencias que normalmente abortan |
| `migrate:generate` | `--baseline` | Genera la migración base a partir del schema existente |
| `migrate:generate` | `--mark-executed` | Marca la baseline como ya aplicada |
## Registro de ejecución
Cada base lleva su propia tabla `HTX_MIGRATIONS` con la versión, el módulo, el nombre,
el lote (*batch*) y las marcas de inicio y fin. El rollback usa el lote para saber qué
revertir en conjunto.
## Panel web
El panel de migraciones está en `admin/migrations/index.php`. Es un PHP independiente,
no un XML de Histrix: permite ver el estado, aplicar pendientes, revertir y crear
migraciones desde el navegador.
:::note
Ante una columna faltante en una base de test, la corrección va en la base —con la
migración correspondiente— y no en el código que la consume. Adaptar una consulta o un
test al schema viejo esconde el problema y lo traslada a producción.
:::
------------------------------------------------------------------------------
## Procesos asíncronos
URL: https://docs.histrix.com.ar/es/gearman/
Worker de Gearman para trabajos en segundo plano y planificador de tareas por base.
------------------------------------------------------------------------------
Histrix resuelve el trabajo que no puede correr dentro del request por dos vías
distintas: un *worker* de Gearman para trabajos disparados por el usuario, y un
planificador propio para tareas recurrentes.
## Worker de Gearman
El motor encola en Gearman dos tipos de trabajo:
| Trabajo | Origen |
| --- | --- |
| `processContainer` | Grabación de un contenedor en segundo plano |
| `send_email` | Envío de correo |
Los trabajos se encolan con `doBackground` contra el servidor local, de modo que el
request devuelve la respuesta sin esperar a que terminen.
### Instalación
```bash
sudo apt-get install gearman php-gearman
```
### Servicio
El worker es `cgi-bin/gearman_worker.php` y se ejecuta como servicio de systemd. La
unidad viene incluida en la instalación:
```bash
sudo cp /usr/share/histrix/cgi-bin/histrix_worker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable histrix_worker.service
sudo systemctl start histrix_worker.service
```
Verificación:
```bash
systemctl status histrix_worker.service
```
El servicio está configurado con `Restart=always`, así que se levanta de nuevo si el
worker termina.
:::note
Si Gearman no está instalado, las operaciones que lo usan no se encolan. Conviene
verificar el estado del servicio cuando se reporta que "no llegan los correos" o que
una grabación larga quedó sin efecto.
:::
## Planificador de tareas
Las tareas recurrentes de cada base se definen en la tabla `HTX_CRONTAB` y se
administran desde la interfaz o por API (`/api/db/{db}/crontab/`). Cada fila tiene una
expresión cron estándar, el comando a ejecutar y el usuario con cuya sesión debe
correr.
El planificador evalúa qué tareas corresponden en el momento de la invocación y las
ejecuta:
```bash
php histrix scheduler {base}
```
Ese comando es el que se engancha al cron del sistema, una vez por base:
```
* * * * * cd /usr/share/histrix && php histrix scheduler cliente >> /var/log/histrix-cron.log 2>&1
```
Cada tarea se ejecuta con la sesión del usuario declarado en la fila, de modo que los
permisos y los datos de contexto sean los de ese usuario y no los del proceso del cron.
------------------------------------------------------------------------------
## Servidor de notificaciones
URL: https://docs.histrix.com.ar/es/pushserver/
Servidor WAMP para notificaciones en tiempo real: publicación desde PHP y suscripción desde el navegador.
------------------------------------------------------------------------------
Histrix incluye un servidor de notificaciones en tiempo real construido sobre
[Thruway](https://github.com/voryx/Thruway) y Ratchet. Implementa WAMP: el servidor
actúa como router de mensajes y los clientes publican o se suscriben a canales.
## Inicio
```bash
php histrix push-server [0.0.0.0:8888]
```
Sin argumentos escucha en `0.0.0.0:8888`. El router usa el realm `realm1` y autentica a
los clientes con WAMP-CRA contra los usuarios de la base.
:::note
En una instalación con Docker, el puerto 8888 solo hace falta publicarlo en el
`docker-compose.yml` si se va a levantar este servidor. Una instalación que no usa
notificaciones en tiempo real no necesita exponerlo. Ver
[Instalación con Nginx y Docker](https://docs.histrix.com.ar/es/instalacion_nginx/).
:::
## Publicación desde PHP
```php
\Histrix\Push\Event::publish($canal, (array) $contenido);
```
```php
\Histrix\Push\Event::publish(
'nueva_oferta',
['xml' => 'oferta_crud.xml', 'user' => 'user_id']
);
```
El canal se prefija automáticamente con el id de la base, de modo que
`nueva_oferta` se publica como `{base}.nueva_oferta` y las bases quedan aisladas entre
sí. Al mensaje se le agregan el usuario que lo emitió y la marca de tiempo.
La publicación se hace por ZMQ hacia `tcp://localhost:5555`, así que el proceso web
necesita la extensión ZMQ de PHP. Si no está cargada, `publish` no hace nada y no
interrumpe la operación en curso.
### Publicación desde un XML
Dentro de un `` de un XML de tipo `nosql`:
```xml
Oferta
```
## Suscripción desde el navegador
El cliente usa [Autobahn](https://github.com/crossbario/autobahn-js). La conexión la
abre el propio motor al iniciar la sesión: se conecta a la ruta `/wss/` del mismo host
—que el servidor web enruta al puerto del push server—, con el realm `realm1` y
autenticación `wampcra`, y queda suscripto al canal personal del usuario
(`{base}.{user_id}`).
```js
var protocol = (window.location.protocol == 'https:') ? 'wss' : 'ws';
var connection = new autobahn.Connection({
url: protocol + '://' + Histrix.host + '/wss/',
realm: 'realm1',
authid: Histrix.user,
authmethods: ['wampcra'],
onchallenge: onchallenge
});
connection.onopen = function (session) {
session.subscribe(Histrix.db + '.' + Histrix.user_id, function (args) {
Histrix.showMsg(args[0] + ' - ' + args[1]);
});
Histrix.wsConnection = session;
};
connection.open();
```
Para suscribirse a un canal adicional desde código propio, con la conexión ya abierta:
```js
if (Histrix.wsConnection && Histrix.wsConnection.isOpen) {
Histrix.wsConnection.subscribe(Histrix.db + '.mi_canal', function (args) {
Histrix.showMsg(args[0]);
});
}
```
Y para publicar desde el navegador:
```js
Histrix.wsConnection.publish(Histrix.db + '.mi_canal', ['Hola']);
```
:::note
El namespace es `\Histrix\Push\Event`. Documentación anterior lo mencionaba como
`\Histrix\Pusher\Event`, que ya no existe.
:::
------------------------------------------------------------------------------
## Plugins
URL: https://docs.histrix.com.ar/es/plugins/
Sistema de plugins: estructura, hooks de PHP y de JavaScript, y configuración.
------------------------------------------------------------------------------
Un plugin agrega funcionalidad al escritorio de Histrix sin modificar el motor. Define
funciones internas y las registra en uno o más *hooks*; el motor las ejecuta en el
momento y lugar correspondientes.
## Ubicación
El cargador de plugins busca en tres lugares, en este orden:
| Ruta | Alcance |
| --- | --- |
| `database/{base}/plugins/` | Solo esa base |
| `plugins/` | Toda la instalación |
| `modules/{módulo}/plugins/` | Las bases que usan ese módulo |
Cada plugin vive en su propio directorio y contiene un archivo de clase con el mismo
nombre que el directorio:
- histrix/
- plugins/
- test/
- test.php
## Estructura de un plugin
La clase extiende `\Histrix\Plugin\Plugin` y registra sus funciones en `init()`:
```php
registerFunction('trayInit', 'display');
$this->registerFunction('statusBarInit', 'status');
}
public function display()
{
echo 'TEST PLUGIN';
}
public function status()
{
echo 'Test Status Bar Plugin
';
}
}
```
## Hooks de PHP
Las funciones registradas con `registerFunction($hook, $función)` se ejecutan desde
PHP.
| Hook | Momento de ejecución |
| --- | --- |
| `preSessionInit` | Antes de inicializar la sesión |
| `desktopInit` | Al iniciar el escritorio de Histrix |
| `statusBarInit` | Al iniciar la barra de estado inferior |
| `trayInit` | Al iniciar el área de notificación del panel superior |
| `javascriptLoad` | Al inicio; debe devolver un arreglo de archivos JavaScript a cargar |
| `javascriptInit` | Al inicio; debe devolver código JavaScript válido |
| `cssLoad` | Al inicio; debe devolver un arreglo de archivos CSS a cargar |
| `afterSysmon` | Al final del monitor de sistema, que corre periódicamente |
| `afterSysmonScripts` | Igual que el anterior; debe devolver un arreglo de sentencias JavaScript |
## Hooks de JavaScript
Se registran desde `init()` con `registerJavascriptFunction($hook, $función)` y se
ejecutan en el navegador:
```php
class test extends \Histrix\Plugin\Plugin
{
public function init()
{
$this->registerJavascriptFunction('afterLoadXml', 'myFunction');
}
}
```
| Hook | Momento de ejecución |
| --- | --- |
| `beforeLoadXml` | Antes de `Histrix.LoadXML` |
| `afterLoadXml` | Después de `Histrix.LoadXML` |
Ambos reciben los mismos parámetros:
```js
function miFuncion(contenido, { programTitle: title, container: xmldatos }) {}
// contenido: variables GET enviadas — xml (nombre del XML) y dir (directorio)
```
## Configuración
Cada plugin puede declarar opciones en `setDefaultOptions()`. El motor las persiste en
la tabla `HTXOPTIONS` con la clave `PLUGIN::{Clase}::{opción}` y las expone en el panel
de configuración, agrupadas por plugin.
Todo plugin recibe automáticamente una opción `enable`, que arranca en `false`: hay que
habilitarlo explícitamente desde la configuración de la base.
```php
class weather extends \Histrix\Plugin\Plugin
{
public function setDefaultOptions()
{
$this->addOption('ciudad', [
'name' => 'Ciudad',
'description' => 'Ciudad para el pronóstico',
'value' => 'Rosario',
]);
}
}
```
El valor se lee con `$this->getParameter('ciudad')`.
## Plugins incluidos
La instalación trae, entre otros: `autoInit` (autoarranque de programas),
`directLink` (enlaces directos a programas), `htxchat`, `htxconfig`, `htxHud` y
`htxHudCmd` (panel de estado y comandos), `htxusermenu`, `lastPrograms`,
`localNews`, `screenSaverLed`, `ShowProfile`, `statusMessage` y `userStatus`.
------------------------------------------------------------------------------
## Localización
URL: https://docs.histrix.com.ar/es/localizacion/
Traducción de la interfaz, del menú y de los contenidos de los XML.
------------------------------------------------------------------------------
Histrix admite la localización de todos sus componentes. El idioma de una instalación se
define con el tag `` en la sección `` de `database/config.xml`.
## Elementos de la interfaz
Las traducciones de los elementos propios de Histrix —botones, mensajes, títulos de
diálogos— están en el directorio `lang/`, un archivo PHP por idioma:
- histrix/
- lang/
- es.php
- en.php
- fr.php
- pt.php
## Menú y contenidos de los módulos
Para traducir los ítems del menú, los módulos y los contenidos de los XML, Histrix usa
archivos `.tmx` (*Translation Memory eXchange*) ubicados en el directorio base de cada
módulo. El nombre del archivo coincide con el del módulo:
- histrix/
- modules/
- histrix/
- histrix.tmx
- proveedores/
- proveedores.tmx
Así, `proveedores.tmx` contiene las traducciones de los programas del módulo de
proveedores.
## Edición de los archivos TMX
Los `.tmx` son XML estándar, editables con cualquier editor de texto o con herramientas
específicas de traducción como
[Virtaal](http://virtaal.translatehouse.org/?id=virtaal/index&redirect=1).
==============================================================================
# Desarrollo
==============================================================================
------------------------------------------------------------------------------
## Tutorial: primera consulta
URL: https://docs.histrix.com.ar/es/tutorial/
Recorrido completo: alta en el menú, XML de consulta, joins, etiquetas, filtros y helpers.
------------------------------------------------------------------------------
Este tutorial construye una consulta desde cero: se da de alta el ítem en el menú, se
escribe el XML, se agregan joins para traer datos de otras tablas y se termina con
filtros y un desplegable de selección.
## Alta del ítem en el menú
El menú del sistema es el de la imagen:
[imagen: Tutorial1]
La primera opción de la tuerquita(engranaje) que esta a la derecha de este menú es “Menus del sistema” cuando la abrimos aparece el árbol de menus:
[imagen: Tutorial2]
En esta parte del sistema se pueden ver editar y agregar nuevos elementos al menú. Lo más sencillo es ver como están ordenados, como están dados de alta y en nuestro caso, que vamos a hacer una consulta en la parte de bancos, copiar parte de lo que ya esta hecho.
El nuevo elemento ya está en la foto es “Consulta de gastos” vamos a ver como lo dimos de alta.
[imagen: Tutorial3]
**Orden:** número que ordena el ítem entre los que comparten el mismo nivel.
**Menú:** el ítem padre. Se copia de otro ítem que esté en el mismo nivel y submenú. Para
agregar el nuevo ítem dentro de "Bancos" → "Consultas", se usa el mismo valor que tienen
los ítems que ya están ahí.
**Título:** el texto que se muestra en el menú.
**Parámetros:** configuraciones del ítem. Para una consulta interesan dos:
- `xml=` nombre del archivo que se ejecuta al elegir el ítem.
- `dir=` directorio donde está ese archivo.
## Organización de archivos y directorios
Los archivos de cada cliente viven bajo el directorio de su base:
- usr/
- share/
- histrix/
- database/
- ElClienteX/
~~~bash
/usr/share/histrix/database//
~~~
Dentro de esta carpeta se genera un árbol de directorios parecido a este:
- ElClienteX/
- ayudas/
- bancos/
- ing/
- man/
- qry/
- test/
- acceptance/
- _support/
- caja/
- ing/
- accesorios/
- class/
- pedidos/
- ruta/
- man/
- proc/
- del/
- qry/
- test/
- acceptance/
- _support/
- calidad/
- ambiente/
- ing/
- man/
- qry/
- clientes/
- inputacion/
- ing/
- mos/
- obleas/
- pre/
- man/
- tests/
- qry/
- tests/
- acceptance/
- _support/
- dasbuard/
Cada directorio dentro de la base representa un módulo, y dentro de cada módulo están los
archivos que invocan los ítems del menú.
Para este ejemplo se crea `gastos_qry.xml` en el directorio `bancos` y se asocia el ítem
"Consulta de gastos" a ese archivo:
[imagen: Tutorial5]
## Contenido del archivo XML
El XML describe una o varias tablas de la base. Este ejemplo trabaja sobre
`REG_MOVIMIENTOS`, que contiene los movimientos —entre ellos los bancarios. Estos son
algunos de sus campos:
[imagen: Tutorial6]
Un primer borrador del archivo:
~~~xml
Consulta de gastos
~~~
La declaración XML y el tag `` son obligatorios. En el `` van los
atributos del programa: `tipo="consulta"` define que es una consulta y `paginar="50"` que
se muestren 50 filas por página. `` y `