Module Builder
Genera código de andamiaje para módulos personalizados de Drupal incluyendo hooks, plugins, entities, services, formularios y tests.
module_builder
Install
composer require 'drupal/module_builder:^4.1'
Overview
Module Builder es una potente herramienta de desarrollo que simplifica el proceso de creación de módulos Drupal generando código de andamiaje. En lugar de crear manualmente código repetitivo y consultar constantemente api.drupal.org para firmas de hooks y parámetros, los desarrolladores pueden usar la interfaz intuitiva de Module Builder para seleccionar los componentes que necesitan.
El módulo analiza el código de tu sitio para descubrir hooks disponibles, tipos de plugins, services y otros componentes de Drupal. Basándose en este análisis, presenta formularios organizados donde puedes seleccionar qué hooks implementar, qué tipos de plugins crear y configurar varios componentes del módulo. El código generado incluye comentarios PHPDoc apropiados, firmas de funciones y estructuras de archivos que siguen los estándares de codificación de Drupal.
Module Builder almacena las definiciones de módulos como entities de configuración, permitiéndote desarrollar iterativamente y regenerar código a medida que cambian los requisitos. Soporta la fusión de código generado con archivos existentes e integra con Git para mostrar el estado de control de versiones de los archivos que se están sobrescribiendo.
Features
- Genera andamiaje completo de módulos incluyendo .info.yml, .module y otros archivos requeridos
- Crea implementaciones de hooks con firmas de funciones, parámetros y comentarios PHPDoc apropiados
- Genera clases de plugins para varios tipos de plugins (Block, Field, Action, Condition, etc.)
- Crea tipos de content entity y config entity con andamiaje completo
- Genera services con inyección de dependencias y definiciones de services apropiadas
- Crea formularios de configuración de administración con enrutamiento de menú y permisos
- Genera elementos de router y rutas dinámicas
- Crea clases de casos de test PHPUnit
- Genera archivos README y otra documentación
- Analiza el código del sitio para descubrir hooks, plugins, services y tagged services disponibles
- Proporciona interfaz de selección de hooks filtrable agrupada por módulo/tipo
- Enlaces a documentación de api.drupal.org para hooks del core
- Almacena definiciones de módulos como entities de configuración para desarrollo iterativo
- Soporta fusión de código generado con archivos de módulos existentes
- Integra con Git para mostrar el estado de control de versiones de los archivos que se modifican
- Soporta adoptar módulos existentes y sus componentes en el builder
- Proporciona autocompletado para selección de services y otros conjuntos de opciones grandes
- Ubicación de escritura de módulos configurable con valores predeterminados inteligentes
- Procesamiento por lotes para análisis de código para manejar bases de código grandes
Use Cases
Crear un nuevo módulo personalizado desde cero
Al iniciar un nuevo módulo, usa Module Builder para generar la estructura inicial. Navega a Module Builder, haz clic en 'Add module', ingresa el nombre y descripción de tu módulo. Luego usa las pestañas para seleccionar qué hooks implementar, agregar clases de plugin, definir servicios y configurar otros componentes. Finalmente, ve a la pestaña Generate y escribe todos los archivos para crear la estructura de tu módulo con el código base apropiado.
Agregar hooks a un módulo existente
Si tienes un módulo existente y necesitas agregar nuevos hooks, primero usa 'Adopt existing module' para crear una entidad de Module Builder para él. Luego ve a la pestaña Hooks, busca y selecciona los hooks que necesitas. Genera el código y usa 'Write selected files' para actualizar solo el archivo .module con las nuevas implementaciones de hooks. La funcionalidad de fusión preservará tu código existente.
Crear un plugin de Block personalizado
Navega a la pestaña Plugins de tu módulo. Agrega un nuevo elemento de plugin y selecciona 'Block' como tipo de plugin. Configura el ID del block, la etiqueta de administración y cualquier configuración que el block deba tener. Genera el código para crear una clase de plugin Block correctamente estructurada en src/Plugin/Block/ con todas las anotaciones y métodos requeridos.
Generar un tipo de entidad de contenido
Usa la pestaña Entity types para definir una nueva entidad de contenido. Configura el ID de la entidad, etiquetas, campos base, handlers (storage, view builder, form, list builder) y configuraciones de interfaz de administración. Module Builder genera la clase de entidad completa, interfaz, clases de formulario, proveedores de rutas y esquema de configuración.
Configurar un formulario de ajustes de administración
En la pestaña Routes & forms, habilita 'Settings form'. Esto genera una clase ConfigFormBase, agrega la ruta a routing.yml, crea un enlace de menú bajo Configuration y configura el permiso asociado. Solo necesitas agregar tus campos de formulario reales y la lógica de envío.
Desarrollo iterativo de módulos
Module Builder almacena la definición de tu módulo como una entidad de configuración. Esto permite el desarrollo iterativo donde puedes regresar, agregar nuevos componentes, regenerar código y usar la funcionalidad de fusión para actualizar archivos mientras preservas tus implementaciones personalizadas. La integración con control de versiones te ayuda a rastrear los cambios.
Tips
- Siempre ejecuta el análisis de código después de instalar o actualizar módulos para asegurar que Module Builder tenga datos actuales sobre los hooks y componentes disponibles.
- Usa control de versiones (Git) antes de escribir archivos para revisar y revertir cambios fácilmente. Module Builder muestra el estado de Git para ayudarte a identificar sobrescrituras riesgosas.
- El botón 'Write new files' es el más seguro para módulos existentes - solo crea archivos que aún no existen.
- Para servicios con muchas opciones, usa la búsqueda con autocompletado. Los caracteres '.' y '_' son intercambiables al buscar.
- Las definiciones de módulos se almacenan como entidades de configuración, por lo que puedes exportarlas con Configuration Management y compartirlas entre entornos.
- La función 'Adopt existing module' es poderosa para incorporar módulos heredados bajo la gestión de Module Builder.
- Usa el filtro en la página Hooks para encontrar hooks rápidamente - solo comienza a escribir parte del nombre del hook.
- Marca la opción 'Clear all caches before analysis' cuando hayas modificado código de módulos personalizados para asegurar un descubrimiento actualizado.
Technical Details
Admin Pages 14
/admin/config/development/module_builder
Página principal de listado que muestra todas las entidades de módulo creadas con Module Builder. Desde aquí puede crear nuevos módulos, editar los existentes, generar código o eliminar definiciones de módulos.
/admin/config/development/module_builder/add
Formulario para crear una nueva definición de módulo. Introduzca la información básica del módulo incluyendo el nombre máquina, nombre legible y ubicación de escritura opcional.
/admin/config/development/module_builder/manage/{module_builder_module}
Edita las propiedades básicas de un módulo incluyendo su nombre, descripción, paquete, dependencias y estado del ciclo de vida. Esta es la primera pestaña al editar un módulo.
/admin/config/development/module_builder/manage/{module_builder_module}/hooks
Selecciona qué hooks debe implementar el módulo. Los hooks están organizados por grupo (core, node, field, etc.) con búsqueda filtrable. Cada hook muestra su descripción y enlaces a la documentación de api.drupal.org.
/admin/config/development/module_builder/manage/{module_builder_module}/plugins
Configura las clases de plugins a generar para tu módulo. Añade plugins de varios tipos (Block, Field, Action, Condition, etc.) con propiedades configurables para cada instancia de plugin.
/admin/config/development/module_builder/manage/{module_builder_module}/entities
Configura tipos de entidad de contenido y tipos de entidad de configuración para tu módulo. Define propiedades de entidad, campos base, handlers y formularios.
/admin/config/development/module_builder/manage/{module_builder_module}/routes_forms
Configura rutas, rutas dinámicas, formularios de configuración y formularios personalizados para tu módulo.
/admin/config/development/module_builder/manage/{module_builder_module}/tests
Configura clases de tests de PHPUnit para tu módulo incluyendo tests unitarios, tests de kernel y tests funcionales.
/admin/config/development/module_builder/manage/{module_builder_module}/misc
Configura componentes adicionales del módulo no cubiertos en otras pestañas, como servicios, permisos, bibliotecas y texto de ayuda.
/admin/config/development/module_builder/manage/{module_builder_module}/generate
Visualiza todos los archivos de código generados y escríbelos en el sistema de archivos. Muestra el estado de fusión de archivos y el estado de control de versiones de Git para archivos existentes.
/admin/config/development/module_builder/manage/{module_builder_module}/adopt
Adopta componentes existentes de los archivos de un módulo en Module Builder. Esto te permite mejorar componentes existentes importándolos primero en el constructor.
/admin/config/development/module_builder/adopt-module
Crea una nueva entidad de Module Builder a partir de un módulo existente en tu sitio. Esto analiza el módulo y crea una definición que puede usarse para regenerar y extender el módulo.
/admin/config/development/module_builder/settings
Configura los ajustes de Module Builder incluyendo el directorio de almacenamiento de datos y opciones de generación de código.
/admin/config/development/module_builder/analyse
Ejecuta el análisis de código para descubrir hooks, plugins, servicios y otros componentes de Drupal disponibles en el código base de tu sitio. Estos datos son necesarios antes de generar cualquier código de módulo.
Permissions 1
Hooks 1
hook_module_builder_info
Proporciona información sobre archivos de definición de hooks a Module Builder. Permite a los módulos especificar fuentes de documentación de hooks personalizadas y archivos de destino.
Troubleshooting 6
Necesitas ejecutar el análisis de código antes de usar Module Builder. Ve a Administration > Configuration > Development > Module Builder > Analyse code y haz clic en 'Perform code analysis' o 'Update code analysis'.
Verifica que el directorio de archivos public:// sea escribible por el servidor web. Comprueba que la configuración data_directory en los ajustes de Module Builder apunte a una ubicación válida.
El análisis de código puede estar desactualizado. Ve a la página Analyse code y ejecuta un nuevo análisis. Si has agregado código personalizado, marca 'Clear all caches before analysis' antes de ejecutar.
Asegúrate de estar usando la última versión tanto de module_builder como de drupal-code-builder. Ejecuta 'composer update drupal/module_builder' para obtener actualizaciones.
Esto ocurre frecuentemente cuando los datos de análisis están desactualizados. El mensaje de error sugerirá volver a ejecutar el análisis de código. Sigue el enlace para actualizar tus datos de análisis.
Esto es informativo. Module Builder detecta el módulo existente e intentará fusionar el código generado con los archivos existentes. Usa control de versiones para revisar los cambios antes de confirmarlos.
Security Notes 4
- Module Builder tiene la capacidad de escribir archivos en el código base de tu sitio. NUNCA debe instalarse en sitios de producción.
- El permiso 'create modules' está marcado como 'restrict access' porque otorga poderosas capacidades de escritura de archivos.
- El código generado debe revisarse antes del despliegue, especialmente cuando se fusiona con archivos existentes.
- No uses Module Builder en sitios de desarrollo accesibles públicamente sin controles de acceso apropiados.