Download the PHP package miguelex/php-template without Composer

php-template

Plantilla base para proyectos PHP 8.2 con arquitectura MVC, tooling moderno y soporte para desarrollo con agentes IA.

🇬🇧 English README

¿Qué incluye?

🏗 Arquitectura MVC

• Router — registro de rutas GET/POST/PUT/PATCH/DELETE, soporte _method override, middleware global, manejo de 404/500
• ActiveRecord — ORM ligero sobre PDO con prepared statements, find, where, save, delete, validación, alertas
• EmailService — envío SMTP vía PHPMailer con templates HTML base
• Html helper — escape seguro, CSRF, alertas en vista, dump de debug

✅ Calidad de código PHP

• PHPStan nivel 6 — análisis estático
• PHP_CodeSniffer — PSR-12
• PHP-CS-Fixer — autocorrección de estilo
• PHPUnit 11 + Pest 3 — tests unitarios, integración y feature

⚡ Frontend (modo fullstack)

Dos opciones de bundler, elige la que prefieras:

Linting y tests front:

• ESLint + Stylelint
• Vitest — tests unitarios JS
• Playwright — tests E2E

🤖 Preparado para agentes IA

Ficheros .agent/ leídos automáticamente por Claude Code, Cursor y similares:

• AGENTS.md — permisos, restricciones, comandos disponibles
• CONVENTIONS.md — PSR-12, BEM, Conventional Commits
• PROJECT.md — contexto de negocio (rellenar por proyecto)
• TASKS.md — backlog de tareas

🔄 CI/CD

GitHub Actions con dos jobs paralelos: PHP QA (PHPStan + PHPCS + PHPUnit + Pest) y Front QA (ESLint + Stylelint + Vitest + Playwright).

Requisitos

Windows

• Instalar PHP desde windows.php.net o via Laragon / XAMPP
• Instalar Node.js desde nodejs.org
• Añadir PHP y Composer al PATH
• El script dev.sh requiere WSL o Git Bash; alternativamente usar npm run dev directamente

WSL (Windows Subsystem for Linux)

macOS

Linux (Ubuntu/Debian)

Crear un nuevo proyecto

Opción A — Clonar y usar el script init-project.sh

El script es interactivo y pregunta:

1. Nombre del proyecto (se usará como nombre de directorio y en composer/package.json)
2. Modo: backend-only o fullstack

También acepta argumentos directos:

El script genera ./mi-proyecto/ con:

• Git inicializado (commit inicial limpio, sin historia de la plantilla)
• Ficheros personalizados con el nombre del proyecto
• Modo backend elimina automáticamente gulpfile, vite.config, tests/front, etc.

Opción B — Fork en GitHub

1. Hacer fork del repositorio
2. Clonar tu fork: git clone https://github.com/TU_USER/php-template.git mi-proyecto
3. Eliminar la historia: rm -rf .git && git init && git add . && git commit -m "chore: init"
4. Ajustar manualmente composer.json y package.json

Instalación (tras crear el proyecto)

Editar .env con los valores reales del proyecto:

Desarrollo

Arrancar el entorno

Opción 1 — concurrently (recomendado en Windows/WSL sin tmux)

Cada proceso aparece con prefijo de color: [PHP] en azul, [GULP]/[VITE] en verde/amarillo.

Opción 2 — dev.sh con tmux (Linux/macOS/WSL)

Atajos tmux: Ctrl+B → flechas para moverse entre paneles · Ctrl+B → D para desconectar · tmux attach -t dev para reconectar.

Opción 3 — Terminales manuales

Compilar assets

Comandos de calidad

PHP

Front (fullstack)

Estructura del proyecto

Decisiones de diseño

¿Por qué sin framework como Laravel/Symfony? Para proyectos donde el overhead de un framework completo no está justificado: módulos de negocio específicos, integraciones con sistemas legacy, o proyectos donde el control fino sobre cada capa es importante.

¿Gulp o Vite? Ambos están disponibles. Gulp es ideal si el JS es simple (unas funciones, jQuery): pipeline directo, sin módulos, sin bundling. Vite es mejor si empiezas a usar import/export, necesitas HMR instantáneo, o prevés que el front crezca.

¿Por qué PHPStan nivel 6 y no 9? El nivel 9 en un proyecto real con código legacy o integraciones externas genera decenas de falsos positivos. El 6 ofrece el 90% del valor sin el ruido. Se puede subir gradualmente.

ActiveRecord vs Repository Para proyectos pequeños/medianos ActiveRecord es más directo. Si el dominio crece, el patrón Repository es el paso siguiente: extraer la lógica de acceso a datos de los modelos a clases UserRepository, etc.

Contribuir

¡Las contribuciones son bienvenidas! Esto incluye mejoras al core MVC, nuevas features de tooling, correcciones, documentación o ejemplos adicionales.

Antes de abrir un PR

1. Haz fork del repositorio y clona tu fork

2. Crea una rama descriptiva:

3. Asegúrate de que composer qa pasa en verde antes de hacer push
4. Si añades código PHP, añade también sus tests
5. Sigue las convenciones de Conventional Commits:

Tipos de contribución bienvenidas

• 🐛 Bug fixes — con test que reproduzca el fallo
• ✨ Features — discutir primero en un issue si es algo grande
• 📖 Documentación — mejoras al README, comentarios en código
• 🧪 Tests — más cobertura siempre es bienvenida
• 🌐 Compatibilidad — mejoras para Windows, macOS, distintas versiones de PHP

Tipos de contribución que no encajan

• Añadir dependencias de frameworks completos (Laravel, Symfony, etc.)
• Cambios de estilo sin funcionalidad asociada
• Romper compatibilidad con PHP 8.2

Flujo de un PR

En el PR describe:

• Qué hace el cambio
• Por qué es necesario
• Cómo probarlo

Licencia

MIT — ver LICENSE.

Agradecimientos

Inspirado en el mini-framework de codigoconjuan, modernizado con PHP 8.2, PDO, typed properties y tooling actual.

CLI — bin/console

La plantilla incluye una herramienta de línea de comandos para las tareas más comunes:

O con Make:

Patrones disponibles: ActiveRecord vs Repository

ActiveRecord — para proyectos simples/medianos

Repository — para proyectos con dominio complejo

Makefile

En Windows sin WSL, instalar make con:

Sistema de agentes IA — estructura completa

Los agentes que leen AGENTS.md de forma nativa (Claude Code, Cursor en modo agente) cargan automáticamente todo el contexto. El fichero WORKFLOW.md garantiza que el agente planifica antes de actuar, hace cambios quirúrgicos, y aprende de los errores del proyecto.