Boilerplate Profissional (Bootstrap Edition)

Starter moderno e “Enterprise-Ready” pré-configurado com Bootstrap 5, Docker Compose V2, ferramentas de QA, análise estática e CI/CD.

---

📋 Sobre o Projeto

Este repositório fornece uma fundação sólida para projetos em Laravel 12, já configurado com a stack clássica de mercado (Bootstrap 5 + SASS). Focado em qualidade, padronização e ambiente Docker robusto (Sail).

---

📚 Documentação de Referência

Centralizamos aqui todos os manuais necessários para trabalhar neste projeto:

• 📖 Documentação Oficial do Laravel 12 Referência completa sobre o framework, rotas, controllers e segurança.

• 📘 Guia Técnico do Projeto Entenda as decisões de arquitetura (Bootstrap vs Tailwind, Docker no Windows).

• 📙 Conceitos Técnicos & Glossário Explicação detalhada sobre Sail, Pint, Larastan, Vite e configurações do PHP.

---

🛠️ Tecnologias e Recursos

• Framework: Laravel 12
• Linguagem: PHP 8.2+
• Frontend: Bootstrap 5 + SASS (via Vite)
• Banco de Dados: PostgreSQL 16 (Docker)
• Ambiente de Desenvolvimento: Laravel Sail (Docker Compose V2)
• Code Style: Laravel Pint (PSR-12)
• Análise Estática: Larastan (PHPStan – Level 5)
• CI/CD: GitHub Actions
• Extras: IDE Helper, Redis, Mailpit

---

🚀 Instalação

⚙️ Requisitos do Ambiente (php.ini)

Caso você opte por rodar o projeto sem Docker (instalação nativa), garanta que as seguintes extensões estejam habilitadas no seu arquivo php.ini:

• ctype
• curl
• dom
• fileinfo
• filter
• hash
• mbstring
• openssl
• pcre
• pdo
• pdo_pgsql (Driver do Banco de Dados)
• session
• tokenizer
• xml

Nota: Se você estiver usando Laravel Sail (Docker), pode ignorar esta lista. O container já vem com todas essas extensões configuradas e otimizadas automaticamente.

---

1. Clone o Repositório

git clone https://github.com/SEU-USUÁRIO/laravel-v12.git
cd laravel-v12

2. Instale as Dependências

Opção A — Composer Local

composer install

Opção B — Composer via Docker

docker run --rm -u "$(id -u):$(id -g)" \
  -v "$(pwd):/var/www/html" -w /var/www/html \
  laravelsail/php82-composer:latest \
  composer install --ignore-platform-reqs

3. Configure o Ambiente

Crie o arquivo .env. Importante: Se estiver no Windows, veja a seção de "Solução de Problemas" abaixo sobre o WWWUSER.

cp .env.example .env

No .env, ajuste o banco para PostgreSQL:

DB_CONNECTION=pgsql
DB_PORT=5432

# Se estiver no Windows, adicione também:
WWWUSER=1000
WWWGROUP=1000

4. Inicialize os Containers

./vendor/bin/sail up -d
# OU, se o comando sail falhar no Windows:
docker compose up -d

5. Setup Final & Frontend

Gere a chave, migre o banco e compile os assets do Bootstrap:

# Backend Setup
docker compose exec laravel.test php artisan key:generate
docker compose exec laravel.test php artisan migrate

# Frontend Setup (Instala e compila Bootstrap/SASS)
docker compose exec laravel.test npm install
docker compose exec laravel.test npm run build

Aplicação disponível em: http://localhost

---

❓ Solução de Problemas Comuns (Troubleshooting)

Erro: "Unsupported operating system" ou Sail não roda.

Se você usa Windows (Git Bash/Mingw), o script ./vendor/bin/sail pode falhar. Solução: Use os comandos nativos do Docker Compose:

• Em vez de sail up, use docker compose up. -Em vez de sail npm run..., use docker compose exec laravel.test npm run....

Erro: "groupadd: invalid group ID" (Docker build fail).

Se o container falhar ao subir com erro de groupadd, é porque o Docker no Windows não detectou seu ID de usuário. Solução: Adicione estas duas linhas ao final do seu arquivo .env:

WWWUSER=1000
WWWGROUP=1000

Depois reconstrua: docker compose up -d --build.

---

🛡️ Qualidade e Ferramentas de QA

🎨 Formatação — Laravel Pint

docker compose exec laravel.test ./vendor/bin/pint

🔎 Análise Estática — Larastan

docker compose exec laravel.test ./vendor/bin/phpstan analyse

🧪 Testes Automatizados

docker compose exec laravel.test php artisan test

🧠 Atualizar IDE Helper

docker compose exec laravel.test php artisan ide-helper:generate

---

🤖 CI/CD — GitHub Actions

O workflow laravel.yml executa automaticamente:

1. Verificação de padrão de código (Pint)
2. Análise estática (Larastan)
3. Testes completos

Tudo isso ao enviar alterações para a branch main.

---

📂 Arquivos Importantes

• compose.yaml — Serviços Docker (App, DB, Redis, Mailpit)
• vite.config.js — Configuração do Build (Bootstrap/SASS).
• phpstan.neon — Regras do PHPStan / Larastan
• pint.json — Configurações do Laravel Pint
• .editorconfig — Padronização entre editores

---

👩‍🎓 Autoria

Desenvolvido com 💛 por Angel Luz.

Se quiser conversar, colaborar ou oferecer uma oportunidade:

📬 E-mail: contatoangelluz@gmail.com
🐙 GitHub: @angelluzk
💼 LinkedIn: linkedin.com/in/angelitaluz
🗂️Website / Portfólio: meu_portfolio/

---

“Transformando código em fluxo, e ideias em movimento.”