Guia Detalhado para Instalar e Configurar o Laravel

Q: Preciso reiniciar o servidor após modificar o .env?

Sim. php artisan serve recarregará as alterações automaticamente, mas php-fpm requer php artisan config:clear ou uma reinicialização do serviço. Em ambientes de produção onde config:cache foi executado, o cache deve ser reconstruído.

Q: Como as alterações no .env entram em vigor após executar config:cache ?

Simplesmente execute php artisan config:cache para regenerar o cache. Isso relerá o .env e todos os arquivos config e gerará novos arquivos de cache.

A configuração é o "painel de instrumentos" do Laravel — entender a relação entre .env e config/ é como ter acesso ao painel de um carro, permitindo ajustar os parâmetros do motor a qualquer momento.

1. O Que Você Vai Aprender

Arquivos de ambiente .env e mecanismo de carregamento de configuração config/*.php
Troca de ambiente: política de configuração local/staging/production
Configuração de conexão com banco de dados (MySQL & PostgreSQL)
Configuração de drivers de cache e sessão
php artisan config:cache Configurando o cache no ambiente de produção

2. Uma História Real do Mundo das Operações

(1) Dor: Configuração de ambiente de desenvolvimento desorganizada

Alice usava MySQL enquanto desenvolvia o ShopMetrics localmente, mas após implantá-lo no servidor de staging, não conseguia conectar ao banco de dados — porque havia codificado DB_PASSWORD no código, e quando enviou para o Git, foi sobrescrito pela senha local do seu colega Bob. Para piorar, Charlie acidentalmente fez commit do APP_DEBUG=true do ambiente de produção para o repositório, expondo todo o rastreamento de pilha de erros aos usuários. Os três levaram dois dias para solucionar todos os problemas de configuração.

(2) Solução para configuração .env

O Laravel usa arquivos .env para isolar variáveis de ambiente — um para cada ambiente local, staging e produção — e nunca codifica valores sensíveis no código.

BASH

# .env (local — nunca faça commit deste arquivo)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics_local
DB_USERNAME=root
DB_PASSWORD=secret

APP_DEBUG=true

(3) Resultado

Depois que Alice gerenciou a configuração usando .env, os ambientes local e de produção não interferem mais um no outro, e APP_DEBUG desliga automaticamente no ambiente de produção, então Bob nunca mais enfrentará o problema de sobrescrição de senha.

3. Mecanismo de Configuração de Ambiente

O sistema de configuração do Laravel consiste em duas camadas: o arquivo .env armazena variáveis de ambiente, e o arquivo config/*.php lê e organiza essas variáveis.

graph TD
    A[Arquivo .env] -->|dotenv carrega| B[$_ENV / $_SERVER]
    B -->|config lê| C[config/database.php]
    C -->|helper env| D["env('DB_HOST', 'localhost')"]
    D -->|fallback| E[Valor padrão se não definido]

(1) Explicação Detalhada do Arquivo .env

Os arquivos .env estão localizados no diretório raiz do projeto e usam o formato KEY=VALUE; nunca os envie para o Git.

Regra	Descrição
Formato	`KEY=VALUE`, sem espaços em nenhum lado do sinal de igual
Aspas	Use aspas para valores contendo espaços: `APP_NAME="My App"`
Comentários	Linhas começando com `#` são comentários
Tipo	Todos os valores são strings; você deve converter o tipo manualmente no código
Prioridade	Variável de ambiente real > valor do arquivo `.env`

(2) Estrutura do Diretório config

config/ retorna um array de configuração para cada arquivo PHP e lê variáveis de ambiente usando a função env().

Arquivo	Finalidade
`app.php`	Nome do App, Fuso Horário, Chave de Criptografia, Modo Debug
`database.php`	Conexão com Banco de Dados, Migração de Nome de Tabela
`cache.php`	Drivers de Cache (file/redis/database)
`session.php`	Drivers de Sessão e Ciclo de Vida
`mail.php`	Configuração do Serviço de Email
`filesystems.php`	Driver de Armazenamento de Arquivos

(1) ▶ Exemplo: Visualizando os valores de configuração atuais

BASH

# Verificar um valor de configuração específico
php artisan tinker
# No REPL do tinker:
config('app.name')
# => "Laravel"

config('database.default')
# => "mysql"

config('cache.default')
# => "file"

Saída:

TEXT

# Comando executado com sucesso

4. Configuração do Banco de Dados

(1) Configuração MySQL

PHP

// config/database.php — conexão 'mysql'
'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'shopmetrics'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
],

(2) Configuração PostgreSQL

PHP

// config/database.php — conexão 'pgsql'
'pgsql' => [
    'driver' => 'pgsql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE', 'shopmetrics'),
    'username' => env('DB_USERNAME', 'postgres'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
],

Dimensão	MySQL	PostgreSQL
Porta Padrão	3306	5432
Suporte JSON	Nativo no 5.7+	Nativo e Mais Poderoso
Busca de Texto Completo	Básica	Avançada (tsvector)
Extensibilidade	Média	Alta (PostGIS, etc.)
Casos de Uso	E-commerce/Conteúdo	Geografia/Análise

(1) ▶ Exemplo: Configurando a conexão MySQL para o ShopMetrics

BASH

# .env — Configurar MySQL para o ShopMetrics
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!

# Criar o banco de dados
mysql -u root -p -e "CREATE DATABASE shopmetrics;"
mysql -u root -p -e "CREATE USER 'shopmetrics_user'@'localhost' IDENTIFIED BY 'Str0ngP@ssw0rd!';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON shopmetrics.* TO 'shopmetrics_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

# Testar conexão
php artisan db:show
# Database: shopmetrics | MySQL 8.x | Tables: 0

Saída:

TEXT

# Comando executado com sucesso

5. Drivers de Cache e Sessão

(1) Comparação de Drivers de Cache

Driver	Casos de Uso	Performance	Persistência
`file`	Desenvolvimento/Projetos Pequenos	Lento	✅
`database`	Sem Redis	Médio	✅
`redis`	Ambiente de Produção	Rápido	✅
`memcached`	Leituras de alta concorrência	Rápido	❌
`array`	Teste	Extremamente rápido	❌

(2) Comparação de Drivers de Sessão

Driver	Cenários Aplicáveis	Descrição
`file`	Desenvolvimento	Armazenado em `storage/framework/sessions/`
`database`	Médio porte	Requer criação da tabela "sessions"
`redis`	Produção	Alta performance, suporte a TTL
`cookie`	Leve	Armazenado no cliente após criptografia, limitado a 4KB
`array`	Teste	Desaparece quando a requisição termina

(1) ▶ Exemplo: Configurando cache e sessões com Redis

BASH

# .env — Configurar Redis para cache e sessão
CACHE_DRIVER=redis
SESSION_DRIVER=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Instalar extensão PHP do Redis
pecl install redis

# Testar conexão Redis
php artisan tinker
# Cache::put('test_key', 'hello', 60)
# => true
# Cache::get('test_key')
# => "hello"

Saída:

TEXT

# Comando executado com sucesso

6. Estratégia de Troca de Ambiente

(1) Soluções de Configuração Multi-Ambiente

Solução	Abordagem	Prós e Contras
Múltiplos arquivos .env	`.env.local` / `.env.staging` / `.env.production`	Simples mas requer troca manual
Integração CI/CD	Definir variáveis de ambiente no script de implantação	Seguro mas requer plataforma CI
Laravel Envoyer	Gerenciamento .env no lado do servidor	Ferramenta oficial, mas paga

(2) Diferenças nas Variáveis de Ambiente Principais

Variável	Local	Staging	Produção
`APP_ENV`	local	staging	production
`APP_DEBUG`	true	true	false
`CACHE_DRIVER`	file	redis	redis
`SESSION_DRIVER`	file	redis	redis
`LOG_LEVEL`	debug	info	warning

(1) ▶ Exemplo: Preparando arquivos .env para diferentes ambientes

BASH

# .env.local (desenvolvimento)
APP_ENV=local
APP_DEBUG=true
DB_DATABASE=shopmetrics_dev
CACHE_DRIVER=file
LOG_LEVEL=debug

# .env.staging (servidor de staging)
APP_ENV=staging
APP_DEBUG=true
DB_DATABASE=shopmetrics_staging
CACHE_DRIVER=redis
LOG_LEVEL=info

# .env.production (servidor de produção)
APP_ENV=production
APP_DEBUG=false
DB_DATABASE=shopmetrics
CACHE_DRIVER=redis
LOG_LEVEL=warning

Saída:

TEXT

# Comando executado com sucesso

7. Configurando o Cache

Em um ambiente de produção, o Laravel pode mesclar e armazenar em cache todos os arquivos de configuração em um único arquivo PHP, evitando a necessidade de ler .env e analisar config/*.php a cada requisição.

(1) ▶ Exemplo: Usando o comando de cache de configuração

BASH

# Armazenar todas as configurações em cache (produção)
php artisan config:cache
# Configuration cached successfully!

# Após o cache, env() retorna null — sempre use config()
# Este é um erro comum!

# Limpar cache de configuração
php artisan config:clear
# Configuration cache cleared!

# Verificar se a configuração está em cache
php artisan config:status
# Config is cached.

Saída:

TEXT

# Comando executado com sucesso

⚠️ Nota: Após executar config:cache, a função env() retornará null em arquivos que não são de configuração. Use env() apenas em config/*.php; use config() em todos os outros lugares.

Comando	Função	Caso de Uso
`config:cache`	Armazenar Configuração em Cache	Implantação em Produção
`config:clear`	Limpar Cache	Após Modificar Configurações
`config:show`	Visualizar Valores de Configuração	Depuração
`env`	Visualizar valores .env	Durante o desenvolvimento

8. Exemplo Abrangente: Configuração de Ambiente Completa para o ShopMetrics

PHP

// ============================================
// Abrangente: Configuração .env completa do ShopMetrics
// Conteúdo: app, banco de dados, cache, sessão, email, logging
// ============================================

// Arquivo .env do ShopMetrics (desenvolvimento local)
/*
APP_NAME=ShopMetrics
APP_ENV=local
APP_KEY=base64:generated-key-here
APP_DEBUG=true
APP_URL=http://localhost:8000

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=shopmetrics-uploads
*/

BASH

# Após configurar o .env, execute estes comandos:
php artisan key:generate
php artisan config:clear
php artisan migrate
php artisan db:seed
php artisan serve

Saída:

TEXT

Application key set successfully.
Configuration cache cleared!
Info: Using MySQL database: shopmetrics
Migration table created successfully.
Starting Laravel development server: http://127.0.0.1:8000

❓ Perguntas Frequentes

P Qual é a diferença entre env() e config()?

R env() lê variáveis de ambiente diretamente do arquivo .env; config() lê valores de configuração organizados nos arquivos config/*.php. Em um ambiente de produção, após executar config:cache, env() retorna null ao acessar arquivos que não são de configuração; portanto, você deve sempre usar config().

P O arquivo .env deve ser enviado ao Git?

R Absolutamente não. O arquivo .env contém informações sensíveis como senhas de banco de dados e chaves de API. Envie apenas .env.example como modelo; o arquivo .env real deve ser criado por operações no servidor.

P Preciso reiniciar o servidor após modificar o .env?

R Sim. php artisan serve recarregará as alterações automaticamente, mas php-fpm requer php artisan config:clear ou uma reinicialização do serviço. Em ambientes de produção onde config:cache foi executado, o cache deve ser reconstruído.

P Quando devo usar SQLite e quando devo usar MySQL?

R Use SQLite para aprendizado e prototipagem (configuração zero); use MySQL para ambientes de produção (recursos empresariais como concorrência, replicação e backup); escolha PostgreSQL quando consultas avançadas (busca de texto completo, GIS) são necessárias.

P Qual é a finalidade do APP_KEY?

R APP_KEY é usado para todas as operações de criptografia (criptografia de sessão, tokens de redefinição de senha, tokens CSRF, etc.). Se você alterar o APP_KEY, todos os dados criptografados se tornarão indecifráveis. Não o altere após a implantação em um ambiente de produção.

P Como as alterações no .env entram em vigor após executar config:cache?

R Simplesmente execute php artisan config:cache para regenerar o cache. Isso relerá o .env e todos os arquivos config e gerará novos arquivos de cache.

📖 Resumo

A configuração do Laravel é organizada em duas camadas: .env armazena variáveis de ambiente, e config/*.php organiza os valores de configuração
Use env() apenas em arquivos de configuração; use config() em todos os outros lugares
MySQL é adequado para cenários de e-commerce, PostgreSQL para cenários de análise, e SQLite para desenvolvimento
Redis é recomendado para ambientes de produção como solução de cache e gerenciamento de sessão
APP_DEBUG deve ser definido como false em um ambiente de produção
config:cache melhora a performance, mas após o cache, env() não funciona mais fora dos arquivos de configuração

📝 Exercícios

Exercício Básico (⭐): Configure o projeto ShopMetrics para usar um banco de dados MySQL. Modifique as informações de conexão do banco de dados no arquivo .env, depois execute php artisan migrate para verificar se a conexão foi bem-sucedida.
Exercício Avançado (⭐⭐): Crie dois arquivos de configuração de ambiente, .env.local e .env.staging, usando nomes de banco de dados e drivers de cache diferentes, e escreva um script para alternar rapidamente entre ambientes.
Desafio (⭐⭐⭐): Investigue os princípios de implementação do config:cache (leia Illuminate/Foundation/Console/ConfigCacheCommand.php), explique por que env() se torna inválido após o cache, e descreva como usar o cache de configuração com segurança em um ambiente de produção.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós

404 Not Found

Guia Detalhado para Instalar e Configurar o Laravel

1. O Que Você Vai Aprender

2. Uma História Real do Mundo das Operações

(1) Dor: Configuração de ambiente de desenvolvimento desorganizada

(2) Solução para configuração .env

(3) Resultado

3. Mecanismo de Configuração de Ambiente

(1) Explicação Detalhada do Arquivo .env

(2) Estrutura do Diretório config

(1) ▶ Exemplo: Visualizando os valores de configuração atuais

4. Configuração do Banco de Dados

(1) Configuração MySQL

(2) Configuração PostgreSQL

(1) ▶ Exemplo: Configurando a conexão MySQL para o ShopMetrics

5. Drivers de Cache e Sessão

(1) Comparação de Drivers de Cache

(2) Comparação de Drivers de Sessão

(1) ▶ Exemplo: Configurando cache e sessões com Redis

6. Estratégia de Troca de Ambiente

(1) Soluções de Configuração Multi-Ambiente

(2) Diferenças nas Variáveis de Ambiente Principais

(1) ▶ Exemplo: Preparando arquivos .env para diferentes ambientes

7. Configurando o Cache

(1) ▶ Exemplo: Usando o comando de cache de configuração

8. Exemplo Abrangente: Configuração de Ambiente Completa para o ShopMetrics

❓ Perguntas Frequentes

📖 Resumo

📝 Exercícios