Download the PHP package wappcode/pdss-utilities without Composer

PDSS-Utilities

Utilidades PHP para trabajar con Doctrine ORM.

Requisitos

• PHP >= 8.0
• Doctrine ORM >= 3.0

Instalación

Instalar la librería usando Composer:

Instalar dependencia de Doctrine ORM

Si aún no tienes Doctrine ORM instalado:

Clases Base para Entidades

Clases abstractas que proveen gestión automática de timestamps (created y updated) y diferentes tipos de identificadores.

AbstractEntityModel

Clase base para entidades con ID tipo integer auto-generado.

Propiedades heredadas:

• id: ?int - Auto-generado por Doctrine
• created: DateTimeImmutable - Timestamp de creación
• updated: DateTimeImmutable - Timestamp de última actualización

AbstractEntityModelUlid

Clase base para entidades con ID tipo ULID (26 caracteres).

Propiedades heredadas:

• id: ?string - ULID de 26 caracteres (sortable por timestamp)
• created: DateTimeImmutable
• updated: DateTimeImmutable

AbstractEntityModelKsuid

Clase base para entidades con ID tipo KSUID (27 caracteres).

Propiedades heredadas:

• id: ?string - KSUID de 27 caracteres (K-Sortable Unique Identifier)
• created: DateTimeImmutable
• updated: DateTimeImmutable

AbstractEntityModelUuidV4

Clase base para entidades con ID tipo UUID v4 (36 caracteres).

Propiedades heredadas:

• id: ?string - UUID v4 de 36 caracteres (formato: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
• created: DateTimeImmutable
• updated: DateTimeImmutable

Métodos Disponibles

Todas las clases abstract proveen:

¿Qué tipo de ID elegir?

AbstractEntityModel (Integer)

Cuándo usar:

• Tablas pequeñas a medianas (< 2 mil millones de registros)
• Sistemas legacy que requieren IDs numéricos
• Cuando el orden de inserción es importante y secuencial
• APIs públicas donde prefieres IDs cortos y simples
• Cuando necesitas operaciones matemáticas con IDs

Ventajas:

• ✅ Tamaño mínimo (4-8 bytes)
• ✅ Índices más rápidos y compactos
• ✅ Fácil de leer y debuggear
• ✅ Compatible con sistemas antiguos

Desventajas:

• ❌ Predecible (riesgo de seguridad en APIs públicas)
• ❌ Revela cantidad de registros
• ❌ Problemas en sistemas distribuidos
• ❌ Límite de ~4 mil millones (INT) o ~9 quintillones (BIGINT)

AbstractEntityModelUlid (26 caracteres)

Cuándo usar:

• Recomendado para la mayoría de casos
• Sistemas modernos que requieren IDs únicos globalmente
• Cuando necesitas ordenamiento cronológico natural
• Microservicios y arquitecturas distribuidas
• Migración desde sistemas con auto-increment

Ventajas:

• ✅ Sortable por tiempo de creación
• ✅ Único globalmente sin coordinación
• ✅ Más compacto que UUID (26 vs 36 caracteres)
• ✅ Case-insensitive (Base32)
• ✅ Legible (no usa caracteres ambiguos)
• ✅ Performance excelente

Desventajas:

• ❌ Más grande que integers (26 bytes vs 4-8)
• ❌ No es estándar universal como UUID

Ideal para: Users, Orders, Products, Posts, Comments

AbstractEntityModelKsuid (27 caracteres)

Cuándo usar:

• Similar a ULID pero con mayor precisión temporal
• Sistemas que requieren ordenamiento muy preciso
• Cuando necesitas timestamp en epoch específico (2014)
• Requerimiento específico de formato KSUID

Ventajas:

• ✅ Sortable por tiempo (epoch 2014)
• ✅ Único globalmente
• ✅ Buena distribución en índices

Desventajas:

• ❌ Case-sensitive (Base62: A-Z, a-z, 0-9)
• ❌ Menos común que ULID o UUID
• ❌ Requiere extensión GMP
• ❌ 27 caracteres (el más largo)

Ideal para: Logs, Events, Audit trails, Time-series data

AbstractEntityModelUuidV4 (36 caracteres)

Cuándo usar:

• Interoperabilidad con sistemas externos que requieren UUID
• Estándares específicos de tu industria
• Cuando la aleatoriedad completa es crítica
• Integración con APIs que esperan UUID
• Sistemas que ya usan UUID y no quieres migrar

Ventajas:

• ✅ Estándar RFC 4122 (universal)
• ✅ Ampliamente soportado
• ✅ Completamente aleatorio (seguridad)
• ✅ Compatible con bases de datos nativas UUID

Desventajas:

• ❌ No sortable (aleatoriedad completa)
• ❌ El más largo (36 caracteres con guiones)
• ❌ Peor performance en índices (fragmentación)
• ❌ Menos legible

Ideal para: Session IDs, API Keys, Integration tokens, External references

Comparación Rápida

Sobreescribir Columnas Heredadas

Puedes personalizar las columnas heredadas en tu entidad usando el atributo #[ORM\AttributeOverride]:

Cambiar nombre de columna

Cambiar longitud del ID

Cambiar nombre de columnas de timestamps

Cambiar tipo de columna ID (integer)

Utilidades de Query

QueryFilter

Aplica filtros dinámicos a un QueryBuilder de Doctrine basado en parámetros HTTP.

Operadores disponibles:

• EQUAL / = - Igualdad
• NOT_EQUAL / != - Diferente
• DIFFERENT / <> - Diferente
• GREATER_THAN / > - Mayor que
• LESS_THAN / < - Menor que
• GREATER_EQUAL_THAN / >= - Mayor o igual
• LESS_EQUAL_THAN / <= - Menor o igual
• LIKE - Búsqueda con comodín
• NOT_LIKE - Búsqueda con comodín negada
• IN - En lista de valores
• NOT_IN - No en lista de valores
• BETWEEN - Entre dos valores
• IS_NULL - Es nulo
• IS_NOT_NULL - No es nulo

Ejemplo:

Filtros con joins:

Filtros compuestos:

QueryJoins

Agrega joins dinámicos a un QueryBuilder.

Tipos de join:

• LEFT - LEFT JOIN (predeterminado)
• INNER - INNER JOIN

Ejemplo:

QuerySelect

Calcula el valor SELECT para queries con selección parcial de propiedades.

Ejemplo:

Sin propiedades específicas:

QuerySort

Aplica ordenamiento dinámico a un QueryBuilder.

Direcciones:

• asc - Ascendente
• desc - Descendente

Ejemplo:

Ordenar por propiedades de joins:

Desde string JSON:

Seguridad en Queries Dinámicas

Datos desde HTTP POST/GET

Las utilidades QueryFilter, QueryJoins, QuerySelect y QuerySort están diseñadas para recibir datos desde peticiones HTTP (POST, GET, etc.). Es fundamental aplicar las validaciones de seguridad adecuadas.

Ejemplo de uso con datos POST:

Protección de Doctrine contra SQL Injection

Doctrine ORM aplica prepared statements y parameter binding automáticamente, lo que protege contra inyección SQL:

✅ Seguro por defecto:

• Todos los valores en QueryFilter se pasan como parámetros vinculados
• Los operadores están validados contra constantes de la clase
• Las propiedades se concatenan como identificadores, no valores

Validaciones de Seguridad Recomendadas

1. Whitelist de propiedades permitidas

2. Whitelist de joins permitidos

3. Limitar operadores permitidos

4. Validar tipos de datos

5. Limitar profundidad de queries

Ejemplo Completo con Seguridad

Checklist de Seguridad

• ✅ Validar propiedades contra whitelist
• ✅ Validar joins contra relaciones permitidas
• ✅ Validar operadores según rol de usuario
• ✅ Validar tipos de valores (numéricos, emails, fechas)
• ✅ Limitar complejidad (joins, filtros, condiciones)
• ✅ Aplicar límites con setMaxResults()
• ✅ Usar permisos basados en roles
• ✅ Log de queries sospechosas para auditoría
• ✅ Rate limiting en endpoints de búsqueda
• ✅ Doctrine se encarga del parameter binding (SQL injection)

Ejemplo Completo