Estructura de archivos: base sólida para escalar tu plugin
Diseñas una estructura profesional para evitar caos al crecer: separarás arranque, servicios, hooks y vistas, con una organización que facilita pruebas, mantenimiento y nuevas funcionalidades.
Una mala estructura no falla el primer día, falla en la cuarta funcionalidad, cuando ya te cuesta mover una pieza sin romper otra.
En esta lección vas a preparar la arquitectura de archivos del plugin WP Avisos Contextuales con separación clara de responsabilidades.
El objetivo no es tener muchas carpetas, sino tener límites claros: qué arranca el plugin, qué registra hooks, qué renderiza salida y qué gestiona ajustes.
Cuando avances a AJAX, bloques dinámicos y seguridad, esta base evitará duplicidad y bugs difíciles de rastrear.
- Cada carpeta debe responder a una pregunta concreta del sistema.
- El archivo principal del plugin debe ser pequeño: declarar metadatos, constantes y delegar en clases internas. Si el entrypoint crece demasiado, estás mezclando orquestación con lógica de negocio.
- La carpeta `includes/` debe contener clases de dominio y servicios técnicos (ajustes, renderer, hooks, repositorios). La carpeta `assets/` solo recursos estáticos (CSS/JS), sin lógica PHP.
- Caso real: plugins que mezclan consultas SQL, HTML y hooks en un solo archivo acaban imposibles de testear y muy caros de mantener.
- Entrypoint mínimo: definición y arranque.
Organiza por responsabilidad, no por ocurrencia
Cada carpeta debe responder a una pregunta concreta del sistema.
El archivo principal del plugin debe ser pequeño: declarar metadatos, constantes y delegar en clases internas. Si el entrypoint crece demasiado, estás mezclando orquestación con lógica de negocio.
La carpeta `includes/` debe contener clases de dominio y servicios técnicos (ajustes, renderer, hooks, repositorios). La carpeta `assets/` solo recursos estáticos (CSS/JS), sin lógica PHP.
Caso real: plugins que mezclan consultas SQL, HTML y hooks en un solo archivo acaban imposibles de testear y muy caros de mantener.
- Entrypoint mínimo: definición y arranque.
- Includes: lógica y servicios reutilizables.
- Assets: interfaz, no reglas de negocio.
Bootstrap limpio: constantes y carga controlada
Si defines bien rutas/versiones desde el principio, evitas hardcodear paths por todo el proyecto.
Define constantes de versión, ruta y URL una sola vez para reutilizarlas en includes, encolado de assets y referencias internas.
Usa `require_once` para dependencias críticas del arranque. Lo importante es que falle pronto y de forma clara si falta un archivo clave.
No cargues todo en bootstrap: instancia una clase principal que registre hooks y reparta responsabilidades.
Flujo de ejecución: de run() a hooks concretos
Tu clase principal no debe hacer todo; debe coordinar.
El método `run()` suele registrar acciones y filtros principales, y delegar a servicios especializados.
Por ejemplo: `SettingsService` para admin, `RendererService` para frontend y `AssetsService` para encolado. Cada servicio conoce su parte y reduce acoplamiento.
Este patrón te permite añadir funciones nuevas sin convertir el plugin en un bloque monolítico inmanejable.
Convenciones que ahorran errores
Nombrar y ubicar bien reduce bugs silenciosos.
Usa prefijos consistentes (`wpac_` en funciones globales y `WPAC\` en clases) para evitar colisiones con otros plugins.
Mantén una regla de nombre de archivos (`class-wpac-*.php`) y una ruta estable para cada tipo de componente.
Documenta en un README interno dónde va cada cosa. Es una inversión mínima con retorno enorme cuando el plugin crece.