README

🛠️ FilamentKit

Kit de inicio para construir paneles profesionales con Filament 4 sobre Laravel 12. Incluye autenticación social, gestión de permisos, monitoreo de correos, exportación a Excel, impersonación, guardián de inactividad y comandos automatizados para preparar cualquier entorno en minutos.

✨ Características destacadas

Área	Qué incluye
🎨 Experiencia	Tema Brisk con modo oscuro, selector de tema y login mejorado.
🔐 Seguridad	Filament Shield con menú de roles, auditoría de actividad y panel administrativo dedicado.
👤 Usuarios	Autenticación clásica + Socialite (GitHub, Google, Microsoft) + impersonación segura.
📈 Observabilidad	Panel administrativo con métricas y bitácora de accesos, log viewer y mails monitor.
📊 Analítica	Widgets listos para Apex Charts y exportación masiva a Excel.
💤 Inactividad	Guardián que cierra sesiones ociosas con aviso configurable.
⚙️ Automatización	Comandos `php artisan project:*` para inicializar, actualizar y optimizar el kit.

🧰 Paquetes incluidos

🎛️ Experiencia de panel

filafly/brisk, filafly/filament-phosphor-icons, awcodes/light-switch, awcodes/overlook, diogogpinto/filament-auth-ui-enhancer, jeffgreco13/filament-breezy, dutchcodingcompany/filament-developer-logins

🛡️ Seguridad y permisos

bezhansalleh/filament-shield, unknow-sk/filament-logger, gboquizosanchez/filament-log-viewer, stechstudio/filament-impersonate, lab404/laravel-impersonate

⚙️ Productividad y operatividad

eightcedars/filament-inactivity-guard, pxlrbt/filament-excel

🔌 Integraciones

dutchcodingcompany/filament-socialite, socialiteproviders/microsoft, backstage/filament-mails, marcelweidum/filament-expiration-notice, leandrocfe/filament-apex-charts

🧑‍💻 Herramientas de desarrollo

barryvdh/laravel-debugbar, barryvdh/laravel-ide-helper, laravel/boost

📦 Compatibilidad

Versión del kit	Filament	PHP
1.x	4.x	>= 8.3

🚀 Instalación guiada

Sigue cada paso en orden; los comandos resaltados son obligatorios para que Shield genere navegación y permisos correctamente.

Crear el proyecto

composer create-project --prefer-dist jrivera/filamentkit nombre-del-proyecto
cd nombre-del-proyecto

Configurar variables

cp .env.example .env
APP_URL=https://tu-dominio.test

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_REDIRECT_URI="${APP_URL}/admin/oauth/callback/github"

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI="${APP_URL}/admin/oauth/callback/google"

MICROSOFT_CLIENT_ID=...
MICROSOFT_CLIENT_SECRET=...
MICROSOFT_REDIRECT_URI="${APP_URL}/admin/oauth/callback/microsoft"
MICROSOFT_TENANT=common

MAIL_MAILER=smtp
MAIL_HOST=...
MAIL_USERNAME=...
MAIL_PASSWORD=...

Preparar dependencias y assets

composer install           # por si agregas dependencias extra
bun install && bun run build

Inicializar la aplicación (orden recomendado)

php artisan key:generate
php artisan migrate
php artisan storage:link
php artisan shield:setup   # genera roles, permisos y menú "Roles & Permissions"
php artisan project:init   # migra, seeders base, permisos y tareas de bootstrap

Actualizar tras cada cambio estructural
- Nuevos recursos, páginas o migraciones → php artisan project:update
- Cambios de configuración o helpers → php artisan project:cache y/o php artisan project:recache
- Necesitas tipados/IDE helpers → php artisan dev:init
- Permisos puntuales sin recrear todo → php artisan shield:generate --all
Checklist post-despliegue
- Revisar config/filament-inactivity-guard.php según políticas de sesión.
- Crear tu usuario administrador y otorgarle el rol super_admin.
- Verificar que el nuevo Panel administrativo (menú Administración) muestre métricas y registros.

🗺️ Módulos del panel

Dashboard principal: limpio, sin widgets intrusivos, ideal para que agregues tus propios KPIs.
Panel administrativo: nueva página que agrupa Overlook (estadísticas de usuarios) y la tabla de accesos recientes.
Roles & Permissions: expuesto vía Filament Shield listo para administrar el RBAC.
Filament Mails: monitor de envíos, eventos y reenvíos desde el mismo panel.

📡 Integraciones explicadas

Socialite extendido – GitHub, Google y Microsoft listos; agrega dominios permitidos desde FilamentSocialitePlugin::authorizeUserUsing.
Filament Mails – Ejecuta php artisan vendor:publish --tag="filament-mails-config" si necesitas personalizar recursos o rutas.
Excel & Exportaciones – Acción masiva disponible en UserResource; puedes añadirla a cualquier tabla con una sola línea.
Inactivity Guard – Valor por defecto: 15 min de inactividad + 60 s de alerta antes del logout. Personaliza en config/filament-inactivity-guard.php.

🧾 Automatizaciones y cuándo usarlas

Comando	Cuándo ejecutarlo	Qué hace
`php artisan project:init`	Proyecto recién clonado o desplegado	Migra DB, genera permisos, ejecuta tareas de arranque.
`php artisan project:update`	Después de crear/actualizar un Resource, Page, Widget o migración	Ejecuta migraciones pendientes y regenera permisos de Shield.
`php artisan shield:setup`	Primera vez (obligatorio) o cuando quieras rehacer la matriz de permisos	Inicializa roles, permisos y asignaciones base.
`php artisan shield:generate --all`	Tras cambios puntuales en recursos sin usar `project:update`	Regenera políticas y permisos detectados.
`php artisan project:cache` / `project:recache`	Cambios en config/env antes de producción	Limpia y vuelve a generar caches de config, rutas y vistas.
`php artisan dev:init`	Cada vez que quieras refrescar helpers IDE o Pint	Ejecuta IDE Helper, Debugbar y demás utilidades de desarrollo.

💡 Sugerencia: crea scripts en tu CI/CD que corran project:init y project:cache para mantener los ambientes sincronizados.

🤝 Contribuciones y soporte

Ajusta o extiende los comandos en app/Console/Commands según las políticas de tu organización.
Crea widgets propios en App\Filament\Admin\Widgets y añádelos al Panel administrativo.
¿Necesitas multi-tenant? Shield y Socialite ya soportan esa arquitectura; sólo habilita el modo correspondiente.

📄 Licencia & Autor

FilamentKit se distribuye bajo la licencia MIT.

Autor: John Rivera González
Correo: johnriveragonzalez7@gmail.com
GitHub: @Johnrivera7

Si este kit te ahorra tiempo, ¡déjame una ⭐️ en GitHub!

jrivera / filamentkit

Maintainers

Details