README

Este paquete proporciona una serie de utilidades y servicios para acelerar el desarrollo de aplicaciones Symfony en el ecosistema Develia.

Características principales

Controladores Base:
- ApiController: Clase base para controladores de API.
- RestController: Implementación básica para controladores REST con métodos GET, POST, PUT y DELETE mapeados automáticamente.
- BaseCrudController: Facilitador para operaciones CRUD estándar.
Servicios de Gestión:
- SettingsManager: Interfaz y servicio para gestionar configuraciones dinámicas (con soporte para base de datos y caché).
- DatabaseLogger: Logger compatible con PSR-3 que persiste los registros en la base de datos (tablas log_entry y log_entry_meta).
- OpenAiService: Integración simplificada con la API de OpenAI.
- JsonSchemaGenerator: Genera JSON Schema a partir de clases PHP (para Structured Outputs de OpenAI).
- YouTrackService: Cliente de la API REST de YouTrack (incidencias, comentarios, usuarios y roles). Configurable con las variables de entorno YOUTRACK_BASE_URL, YOUTRACK_TOKEN y YOUTRACK_PROJECT_ID. Al crear usuarios la contraseña es obligatoria (YouTrack la exige) y, en YouTrack Cloud, deleteUser() no está disponible: usar banUser(). getIssues() y getUsers() aceptan una consulta opcional para filtrar en el servidor (reporter: <login>, login o nombre del usuario…). Los roles se gestionan en Hub (getRoles(), findRole(), getUserRoles(), assignUserRole()), que identifica a los usuarios por su ringId y sólo permite conceder roles sobre proyectos registrados en Hub; para el resto, usar el proyecto global (HUB_GLOBAL_PROJECT_ID, valor por defecto).
- SlackNotifier: Envía notificaciones a Slack mediante un Incoming Webhook. Configurable con la variable de entorno SLACK_WEBHOOK_URL.
- TransactionManager: Utilidad para envolver ejecuciones en transacciones de base de datos.
- LockManager: Gestión de bloqueos (locks) para evitar condiciones de carrera.
Seguridad:
- StaticApiKeyAuthenticator: Autenticador sencillo mediante una clave API estática enviada en las cabeceras.
- ApiKeyAuthenticator y BearerApiKeyAuthenticator: Autenticadores opcionales e independientes que localizan un usuario mediante un cargador configurable usando X-Api-Key o Authorization: Bearer.

Autenticación API/MCP

La librería no crea rutas, servidores MCP, firewalls ni reglas de autorización. La aplicación consumidora puede preparar su entidad Doctrine con ApiKeyUserTrait, sin implementar un contrato adicional al UserInterface requerido por Symfony:

use Develia\Symfony\Security\ApiKeyUserTrait;

class User implements UserInterface
{
    use ApiKeyUserTrait;

    // Implementar aquí el resto de UserInterface.
}

El trait añade una columna Doctrine nullable, única y de hasta 255 caracteres. La aplicación debe generar la migración y no debe incluir apiKey en sus grupos de Serializer ni exponerlo en respuestas.

Por defecto se usa PlainTextApiKeyEncoder. Para almacenar el valor de búsqueda como SHA-256 determinista, sustituye el alias en la aplicación:

services:
    Develia\Symfony\Security\ApiKeyEncoderInterface:
        alias: Develia\Symfony\Security\Sha256ApiKeyEncoder

El mismo encoder debe usarse al crear o rotar la clave y al autenticarla. SHA-256 determinista permite una consulta directa por apiKey y es apropiado para claves aleatorias largas; no sustituye un hash adaptativo para secretos de baja entropía.

$rawApiKey = bin2hex(random_bytes(32));
$user->setApiKey($apiKeyEncoder->encode($rawApiKey));

// Entregar $rawApiKey una sola vez al propietario y no registrarla.

Por defecto, DoctrineApiKeyUserLoader busca el valor codificado en apiKey. Solo hay que indicar la entidad de usuario; la propiedad también puede personalizarse:

parameters:
    develia.security.api_key_user_class: App\Entity\User
    develia.security.api_key_property: apiKey

Para usar Redis, una API remota u otro almacenamiento, implementa ApiKeyUserLoaderInterface y sustituye su alias. La aplicación conecta los autenticadores a sus firewalls API o MCP y sigue siendo responsable de las rutas y la autorización:

services:
    Develia\Symfony\Security\ApiKeyUserLoaderInterface:
        alias: App\Security\ApiKeyUserLoader

security:
    firewalls:
        api:
            stateless: true
            custom_authenticators:
                - Develia\Symfony\Security\ApiKeyAuthenticator
                - Develia\Symfony\Security\BearerApiKeyAuthenticator

ApiKeyAuthenticator usa X-Api-Key por defecto; el parámetro de servicio develia.security.api_key_header permite cambiarlo sin configurar BearerApiKeyAuthenticator. Los dos autenticadores no inspeccionan el transporte del otro ni rechazan su presencia simultánea. Los fallos devuelven 401 sin la credencial y el flujo Bearer añade WWW-Authenticate: Bearer.

Extensiones Twig:
- DateExtension: Filtros adicionales para el manejo de fechas en plantillas.
Utilidades:
- Helpers para manejo de anotaciones, rutas y respuestas XML.

Requisitos

PHP 8.1 o superior.
develia/commons, FrameworkBundle, Serializer, Console, Process, Lock, HttpClient, YAML y el cliente de OpenAI se instalan como dependencias del paquete.
Los componentes Cache, Config, DependencyInjection, EventDispatcher, HttpFoundation, HttpKernel y Routing los aporta FrameworkBundle.

Instalación

Instala el paquete vía Composer:

composer require develia/symfony

La instalación base no incluye Doctrine. Para habilitar BaseRepository, entidades y specifications, mappings ORM, DatabaseLogger, DatabaseSettingsManager, TransactionManager, PdoLockManager, LogEntryRepository y el loader Doctrine de API keys, instala:

composer require doctrine/doctrine-bundle doctrine/orm

El bundle detecta DoctrineBundle, ORM y DBAL y registra automáticamente sus mappings, servicios y aliases. Aunque symfony/lock forma parte de la instalación base, la implementación PdoLockManager solo se registra cuando DBAL está disponible.

La autenticación es opcional y requiere los componentes de seguridad. El loader y los autenticadores de usuario se registran automáticamente cuando también está disponible Doctrine; sin Doctrine, la aplicación puede implementar ApiKeyUserLoaderInterface y registrar manualmente el loader y los autenticadores.

composer require symfony/security-core symfony/security-http

Para habilitar DateExtension, instala Twig:

composer require twig/twig

AnnotationUtilities, los formularios y JsonSchemaGenerator también mantienen sus dependencias opcionales indicadas en las sugerencias de Composer.

Asegúrate de registrar el bundle en tu archivo config/bundles.php si no se hace automáticamente:

return [
    // ...
    Develia\Symfony\DeveliaBundle::class => ['all' => true],
];

Configuración

Puedes configurar los servicios en tus archivos de configuración de Symfony (ej. config/packages/develia.yaml). Consulta los servicios disponibles en el contenedor de servicios de Symfony.

develia / symfony

Maintainers

Package info

Statistics

Security