README

El paquete PHP del proyecto SDUI (interfaz dirigida por servidor) proporciona modelos PHP generados para crear y validar las estructuras JSON de pantallas, componentes, acciones y respuestas de API. Es una biblioteca de modelos: no incluye un servidor HTTP ni renderiza la interfaz.

Requisitos e instalación

PHP 8.0 o posterior
Composer

Instala las dependencias del paquete desde este directorio:

composer install

Carga el autoloader de Composer en tu aplicación:

require __DIR__ . '/vendor/autoload.php';

Las clases generadas utilizan el espacio de nombres Em3\Sdui. Composer asigna ese espacio de nombres al directorio src/Generated/.

Inicio rápido

Las clases PHP de componentes individuales ya identifican el tipo, por lo que puedes crear una instancia sin pasar type:

<?php

require __DIR__ . '/vendor/autoload.php';

use Em3\Sdui\Text;

$text = new Text([
    'id' => 'greeting',
    'variant' => 'h1',
    'content' => 'Hola',
]);

// Los getters generados permiten consultar los campos validados.
$content = $text->getContent();

// Recupera los datos de entrada del constructor.
$data = $text->getRawModelDataInput();

Los constructores reciben un arreglo asociativo y lo validan contra el esquema del modelo. Si falta una propiedad obligatoria, un valor no es válido o se incluye una propiedad adicional no permitida, se lanza una PHPModelGenerator\Exception\ErrorRegistryException.

La propiedad type se puede omitir al crear una instancia de una clase concreta como Text, Button o Container. La clase no agrega esa propiedad automáticamente: si incluyes el componente en el JSON SDUI que enviarás al cliente, agrega type al payload. El esquema de Screen.ui.components la define como discriminador para que el cliente reconozca cada componente.

Las clases generadas también proporcionan métodos getX() para acceder a sus campos. Algunos campos de objetos anidados se representan mediante clases de modelo generadas, mientras que los elementos de arreglos pueden seguir siendo arreglos. Consulta los getters y el esquema del modelo correspondiente para conocer la estructura exacta.

En las propiedades anidadas puedes proporcionar un arreglo asociativo o una instancia de un modelo generado que implemente JSONModelInterface. Por ejemplo, puedes pasar new Style([...]) en styles, o instancias de componentes en children y Screen.ui.components. El validador usa los datos del modelo anidado para validar y construir el tipo que espera esa propiedad.

Salida JSON

Las instancias de los modelos generados no implementan JsonSerializable. Llamar directamente a json_encode($text) no serializa los campos del modelo. getRawModelDataInput() devuelve los datos proporcionados al constructor y puede utilizarse para recuperar la entrada. Si construyes estructuras anidadas con objetos de modelos generados, conviértelos en arreglos de datos desde tu aplicación antes de codificarlos.

Modelos disponibles

Las principales clases generadas están en el espacio de nombres Em3\Sdui:

Pantallas y respuestas: Screen, Successresponse, Errorresponse
Componentes: Button, Container, Date, Dynamiclist, Form, Icon, Image, Input, Map, Password, Select, Tabs, Text, Textinput
Acciones: Dialog, Execute, Mapcontrol, Navigate, Submit, Toast
Valores compartidos: Style

Estos son los nombres de las clases que se generan actualmente en src/Generated/. Ten en cuenta que nombres como Successresponse, Dynamiclist, Mapcontrol y Textinput utilizan exactamente las mayúsculas y minúsculas indicadas; no deduzcas la capitalización de las clases PHP a partir de los nombres usados en la documentación.

Estructura del paquete

php/
├── docs/                 # Referencia de modelos y comportamientos
├── schemas/              # Esquemas JSON que utiliza el generador
├── src/Generated/        # Clases de modelo generadas; no editar manualmente
├── generate-classes.php  # Genera y prepara las clases de modelo
├── post-process-generated-models.php
│                         # Adapta la validación de objetos anidados
└── generate-docs.php     # Añade anotaciones PHPDoc a las clases generadas

Los esquemas describen los campos permitidos, los tipos, los valores obligatorios y los discriminadores de cada modelo. Los constructores PHP generados aplican estas restricciones al crear una instancia. El proyecto genera estos esquemas a partir de sus definiciones de TypeScript/Zod.

Regenerar esquemas y clases PHP

Ejecuta estos comandos desde la raíz del repositorio:

npm run generate:schemas
npm run generate:php

generate:schemas vuelve a crear los esquemas JSON de php/schemas/ a partir de las definiciones de TypeScript. generate:php ejecuta ambos scripts de generación de PHP: generate-classes.php vuelve a crear src/Generated/ a partir de los esquemas, y generate-docs.php añade anotaciones PHPDoc que enlazan cada modelo con su página de referencia. Estos scripts sobrescriben los archivos generados; por eso, modifica los esquemas fuente o las definiciones de TypeScript en lugar de editar las clases generadas. Después de generarlas, generate-classes.php ejecuta post-process-generated-models.php para normalizar los modelos anidados antes de validarlos.

Documentación

Las referencias detalladas están en docs/ y están escritas en español. Empieza por las páginas conceptuales y consulta después la página específica de cada modelo para conocer sus campos, requisitos de validación y ejemplos.

em3 / sdui-php

Package info

Security

Statistics

README

Requisitos e instalación

Inicio rápido

Salida JSON

Modelos disponibles

Estructura del paquete

Regenerar esquemas y clases PHP

Documentación

Conceptos

Componentes

Acciones

Respuestas