SMS Framework
Integra las capacidades de Texter y canal SMS de Symfony Notifier con Drupal, proporcionando funciones de envío de SMS y verificación de números de teléfono.
smsframework
Overview
SMS Framework proporciona capacidades completas de mensajería SMS para Drupal mediante la integración del componente Notifier de Symfony. El módulo soporta el envío de mensajes SMS a través de más de 60 proveedores de SMS, incluyendo Twilio, Vonage, Bandwidth, Brevo, Clickatell, Nexmo, Plivo, Sinch y muchos más.
Una característica clave es el sistema de verificación de números de teléfono, que permite a los administradores del sitio requerir que los usuarios verifiquen sus números de teléfono mediante códigos de verificación por SMS. El sistema de verificación incluye tiempos de expiración configurables, aplicación de números de teléfono únicos, limpieza automática de verificaciones expiradas y protección contra ataques de fuerza bruta.
El módulo proporciona un widget de campo de teléfono especializado que muestra el estado de verificación e instrucciones, guiando a los usuarios a través del proceso de verificación. La configuración se realiza completamente a través de parámetros YAML en lugar de una interfaz de usuario, dando a los desarrolladores control total sobre la configuración de transporte, el comportamiento de verificación y los mapeos de campos de entidad.
Cuando Symfony Messenger está disponible, los mensajes SMS se envían de forma asíncrona a través de colas para mejorar el rendimiento y la fiabilidad.
Features
- Envío de mensajes SMS a través de más de 60 proveedores de SMS mediante configuración DSN de Symfony Notifier
- Sistema de verificación de números de teléfono con códigos de verificación y tiempos de expiración configurables
- Mapeo de entidad a campo de número de teléfono para verificación automática en creación/actualización de entidades
- Widget de campo de teléfono especializado que muestra estado de verificación, temporizador de cuenta regresiva e instrucciones
- Aplicación de números de teléfono únicos para evitar que el mismo número sea verificado en múltiples cuentas
- Protección contra ataques limitando intentos de verificación (5 por cada 6 horas por defecto)
- Limpieza automática de registros de verificación expirados mediante cron y workers de cola
- Soporte de tokens para personalizar mensajes de verificación ([sms-message:verification-code], [sms:verification-url])
- Envío asíncrono de SMS mediante Symfony Messenger cuando está disponible
- Arquitectura basada en eventos que permite que código personalizado intercepte la creación de verificaciones
- Ruta de verificación y URL de redirección de éxito configurables
- Soporte para autocompletado Web OTP de Chrome en el formulario de verificación
Use Cases
Verificación de Número de Teléfono de Usuario
Agregue un campo telephone a las cuentas de usuario y configure el mapeo de entidad para habilitar la verificación automática de teléfono. Cuando los usuarios ingresan su número de teléfono, reciben un SMS con un código de verificación. El widget del campo muestra el estado de verificación y un temporizador de cuenta regresiva. Los usuarios visitan /sms/verify para ingresar su código y completar la verificación.
Envío de SMS Transaccionales
Use el servicio NotifierInterface para enviar notificaciones SMS programáticamente. Cree una Notification con texto de asunto, cree un Recipient con número de teléfono y llame a $notifier->send($notification, $recipient). El mensaje se enruta a través de los transportes SMS configurados.
SMS de Confirmación de Pedido para E-commerce
Después de completar un pedido, recupere el número de teléfono verificado del cliente desde su cuenta de usuario usando SmsPhoneNumberInterface::getPhoneNumbers(). Envíe la confirmación del pedido mediante NotifierInterface. Las verificaciones aseguran que los mensajes lleguen a destinatarios legítimos.
Autenticación de Dos Factores mediante SMS
Requiera que los usuarios verifiquen su número de teléfono como parte de la seguridad de la cuenta. Habilite la aplicación de números de teléfono únicos para prevenir el mismo número en múltiples cuentas. Use el sistema de verificación como bloque de construcción para implementaciones de 2FA.
Notificaciones SMS Masivas
Consulte usuarios con números de teléfono verificados usando consultas de entidad filtradas por entidades sms_phone_number_verification. Envíe notificaciones a múltiples destinatarios pasando múltiples recipients a $notifier->send(). Los mensajes se encolan automáticamente cuando Symfony Messenger está instalado.
Desarrollo y Pruebas
Instale symfony/fake-sms-notifier y configure el DSN como 'fakesms+logger://default' para registrar todos los mensajes SMS en lugar de enviarlos. Útil para entornos de desarrollo y probar flujos de verificación sin incurrir en costos de SMS.
Tips
- Use el DSN fakesms+logger://default durante el desarrollo para ver el contenido de SMS en los logs de Drupal sin enviar mensajes reales
- Configure notifier.channel_policy para controlar qué niveles de importancia activan mensajes SMS
- La plantilla de mensaje de verificación soporta todos los tokens de Drupal además de los tokens específicos de SMS
- Establezca sms.verification.unique en false si necesita permitir el mismo número de teléfono en múltiples cuentas
- Sobrescriba logger.channel.sms.phone_number_verification con Psr\Log\NullLogger si no quiere que los números de teléfono se registren en logs
- Instale el módulo SM (Symfony Messenger) para encolamiento asíncrono automático de SMS en sitios de alto tráfico
- Use QueryOptions con VerificationRequirement::Verified al obtener números de teléfono para solo obtener números verificados
Technical Details
Admin Pages 1
/sms/verify
Formulario de verificación de número de teléfono donde los usuarios ingresan el código de verificación que recibieron por SMS. El formulario valida el código contra los registros de verificación almacenados y marca el número de teléfono como verificado tras el envío exitoso.
Permissions 1
Hooks 6
hook_entity_insert
Activa la creación de verificación de teléfono cuando se crea una nueva entidad con un campo de número de teléfono mapeado.
hook_entity_update
Actualiza las verificaciones de teléfono cuando cambian los números de teléfono de la entidad. Crea nuevas verificaciones para números agregados, elimina verificaciones para números eliminados.
hook_entity_delete
Elimina todas las verificaciones de números de teléfono asociadas con una entidad eliminada.
hook_cron
Purga registros de verificación de números de teléfono expirados durante la ejecución de cron.
hook_token_info
Define tipos de token de SMS Framework: sms, sms-message, sms-recipient, sms-verification-code.
hook_tokens
Proporciona reemplazos de valores de token para los tokens de SMS Framework usados en mensajes de verificación.
Troubleshooting 6
Verifique que su services.local.yml esté incluido en settings.php. Compruebe que el parámetro sms.transports tenga un DSN válido. Asegúrese de haber instalado el bridge correcto de Symfony Notifier para su proveedor (ej., composer require symfony/twilio-notifier). Limpie la caché después de cualquier cambio de configuración.
Aumente el parámetro sms.verification.unverified.lifetime en services.local.yml. El valor por defecto es 900 segundos (15 minutos). Recuerde limpiar la caché después de los cambios.
Este es el comportamiento esperado cuando una verificación está pendiente. Los usuarios deben completar la verificación en /sms/verify antes de que el campo se desbloquee. Si la verificación expiró, guarde la entidad para activar un nuevo código de verificación.
La protección contra ataques limita a 5 intentos por cada 6 horas. Espere a que pase la ventana de protección, o limpie manualmente las entradas de la tabla flood para el evento 'sms.verify_phone_number'.
Asegúrese de que el parámetro notifier.field_mapping.sms mapee correctamente su tipo de entidad, bundle y nombre de campo. Establezca verifications: true en el mapeo. El campo debe existir y ser de tipo telephone.
Verifique que sms.verification.enabled esté en true en la configuración. La ruta se elimina condicionalmente cuando la verificación está deshabilitada. Limpie la caché para reconstruir las rutas.
Security Notes 6
- La protección contra ataques limita los intentos de verificación para prevenir ataques de fuerza bruta (5 intentos por cada 6 horas)
- Los códigos de verificación se almacenan en la base de datos y deben tratarse como datos sensibles
- Los números de teléfono se registran en logs por defecto - sobrescriba el servicio de logger para prevenir el registro si es necesario
- Habilite la aplicación de números de teléfono únicos para prevenir la toma de cuentas mediante números de teléfono compartidos
- Los DSNs de transporte SMS contienen credenciales de API - asegúrese de que services.local.yml no se suba al control de versiones
- El formulario de verificación usa el atributo de autocompletado Web OTP de Chrome para entrada segura de códigos