Configuração de ambiente

Use .env.example apenas como referência local. Em homologação e produção, mantenha valores em um cofre de segredos, gere chaves exclusivas e nunca publique o arquivo .env.

Legenda: obrigatória é necessária para o ambiente recomendado; condicional depende do recurso/driver; opcional usa padrão seguro ou recurso alternativo.

Aplicação

Variável	Nível	Como preencher
APP_NAME	Obrigatória	Nome exibido da aplicação.
APP_ENV	Obrigatória	local, staging ou production, conforme o ambiente.
APP_KEY	Obrigatória	Gere uma vez com php artisan key:generate; não copie entre ambientes.
APP_DEBUG	Obrigatória	false fora do desenvolvimento.
APP_URL	Obrigatória	URL pública canônica, com HTTPS fora do local.
APP_LOCALE, APP_FALLBACK_LOCALE	Obrigatória	Idioma principal e fallback; confirme o comportamento esperado pela equipe.
APP_FAKER_LOCALE	Opcional	Locale usado somente para dados fictícios.
APP_PREVIOUS_KEYS	Condicional	Chaves antigas durante rotação controlada da APP_KEY.
APP_MAINTENANCE_DRIVER, APP_MAINTENANCE_STORE	Opcional	Coordenação de manutenção; store compartilhado em múltiplas instâncias.
BCRYPT_ROUNDS	Opcional	Custo de hash; valide desempenho antes de alterar.

Banco PostgreSQL

Variável	Nível	Como preencher
DB_CONNECTION	Obrigatória	pgsql na arquitetura do projeto.
DB_URL	Condicional	URL única do provedor; substitui os campos separados quando usada.
DB_HOST, DB_PORT	Obrigatória sem DB_URL	Host privado e porta PostgreSQL.
DB_DATABASE, DB_USERNAME, DB_PASSWORD	Obrigatória sem DB_URL	Banco e credencial exclusivos do ambiente.
DB_SSLMODE	Condicional	Política TLS exigida pelo provedor.
DB_CHARSET	Opcional	Preserve o padrão salvo pelo framework salvo exigência comprovada.

Variáveis MySQL, SQLite e SQL Server existentes em config/database.php são alternativas do framework, não a implantação suportada por esta arquitetura.

Redis, cache, sessão e fila

Variável	Nível	Como preencher
REDIS_CLIENT	Obrigatória com Redis	Cliente instalado, normalmente phpredis.
REDIS_URL	Condicional	URL única do provedor.
REDIS_HOST, REDIS_PORT	Obrigatória sem REDIS_URL	Endpoint privado do Redis.
REDIS_USERNAME, REDIS_PASSWORD	Condicional	Credenciais do serviço; não use valor de desenvolvimento em produção.
REDIS_DB, REDIS_CACHE_DB	Opcional	Índices lógicos para dados e cache.
REDIS_PREFIX	Opcional	Prefixo exclusivo quando Redis é compartilhado.
REDIS_PERSISTENT, REDIS_MAX_RETRIES, REDIS_BACKOFF_ALGORITHM, REDIS_BACKOFF_BASE, REDIS_BACKOFF_CAP	Opcional	Ajustes de conexão e retentativa.
CACHE_STORE	Obrigatória	redis na configuração recomendada.
CACHE_PREFIX	Condicional	Necessário quando ambientes compartilham o mesmo serviço.
SESSION_DRIVER	Obrigatória	redis na configuração recomendada.
SESSION_LIFETIME, SESSION_EXPIRE_ON_CLOSE	Opcional	Duração e encerramento da sessão.
SESSION_ENCRYPT	Opcional	Criptografia do conteúdo da sessão.
SESSION_DOMAIN, SESSION_PATH	Condicional	Escopo do cookie.
SESSION_SECURE_COOKIE	Obrigatória em HTTPS	true em produção.
SESSION_HTTP_ONLY, SESSION_SAME_SITE, SESSION_PARTITIONED_COOKIE	Opcional	Política do cookie; altere só com teste de login.
QUEUE_CONNECTION	Obrigatória	redis para processamento assíncrono recomendado.
REDIS_QUEUE_CONNECTION, REDIS_QUEUE, REDIS_QUEUE_RETRY_AFTER	Opcional	Conexão, fila padrão e tempo de reserva.
QUEUE_FAILED_DRIVER	Opcional	Persistência de jobs falhos; mantenha habilitada em produção.

Os workers precisam consumir explicitamente events,whatsapp,workflows,default, mesmo que REDIS_QUEUE defina apenas a fila padrão.

E-mail

Variável	Nível	Como preencher
MAIL_MAILER	Obrigatória quando há e-mail real	smtp ou outro driver configurado.
MAIL_URL	Condicional	URL completa do provedor, se usada.
MAIL_SCHEME, MAIL_HOST, MAIL_PORT	Obrigatória sem MAIL_URL	Transporte e endpoint SMTP.
MAIL_USERNAME, MAIL_PASSWORD	Condicional	Credenciais SMTP.
MAIL_FROM_ADDRESS, MAIL_FROM_NAME	Obrigatória	Remetente autorizado e reconhecível.
MAIL_EHLO_DOMAIN	Opcional	Domínio EHLO exigido pelo provedor.
MAIL_LOG_CHANNEL, MAIL_SENDMAIL_PATH	Opcional	Apenas para drivers correspondentes.
POSTMARK_API_KEY, RESEND_API_KEY	Condicional	Alternativas quando o mailer escolhido usa esses provedores.

Mailpit é somente local. Valide SPF, DKIM e DMARC no provedor antes de produção.

Arquivos

Variável	Nível	Como preencher
FILESYSTEM_DISK	Obrigatória	Use public na implantação atual. Os uploads de atualizações fixam esse disco no código.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Condicional	Credencial do storage compatível com S3.
AWS_DEFAULT_REGION, AWS_BUCKET	Condicional	Região e bucket.
AWS_URL, AWS_ENDPOINT, AWS_USE_PATH_STYLE_ENDPOINT	Opcional	CDN ou endpoint S3 compatível.

Execute php artisan storage:link e preserve storage/app/public. As variáveis AWS configuram o driver S3 do framework, mas não movem automaticamente os uploads atuais, que usam explicitamente public.

Realtime com Reverb

Variável	Nível	Como preencher
BROADCAST_CONNECTION	Obrigatória para realtime	reverb.
REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET	Obrigatória	Trio exclusivo por ambiente.
REVERB_HOST, REVERB_PORT, REVERB_SCHEME	Obrigatória	Destino visto pelo backend; use TLS em produção.
VITE_REVERB_APP_KEY	Obrigatória	Chave pública usada pelo navegador.
VITE_REVERB_HOST, VITE_REVERB_PORT, VITE_REVERB_SCHEME	Obrigatória	Endpoint público visto pelo navegador. Use esquema https para ativar transporte seguro wss; no local, http produz ws.
VITE_APP_NAME	Opcional	Nome exposto no bundle web.

Variáveis VITE_* são incorporadas no build: alterá-las exige recompilar os assets. Pusher e Ably continuam disponíveis como drivers do framework, mas não fazem parte do caminho recomendado; suas variáveis só são necessárias se o driver for trocado conscientemente.

Meta e WhatsApp

Variável	Nível	Como preencher
WHATSAPP_ENABLED	Obrigatória	Ative somente quando a integração estiver pronta.
WHATSAPP_API_VERSION	Obrigatória ao ativar	Versão suportada da Graph API, revisada em upgrades.
META_APP_ID	Obrigatória para Embedded Signup	ID do app Meta.
META_APP_SECRET	Obrigatória em produção	Segredo usado no OAuth e assinatura dos webhooks.
META_CONFIG_ID	Obrigatória para Embedded Signup	ID da configuração criada na Meta.
META_REDIRECT_URI	Obrigatória para Embedded Signup	URL HTTPS exata do callback OAuth.
META_WEBHOOK_VERIFY_TOKEN	Obrigatória	Valor aleatório exclusivo usado na verificação do webhook global.

Veja o passo a passo em WhatsApp.

Logs e integrações alternativas

Variáveis	Nível	Uso
LOG_CHANNEL, LOG_STACK, LOG_LEVEL	Obrigatória	Destino e nível dos logs. Evite debug em produção.
LOG_DEPRECATIONS_CHANNEL, LOG_DEPRECATIONS_TRACE, LOG_DAILY_DAYS	Opcional	Deprecações e retenção local.
LOG_SLACK_WEBHOOK_URL, LOG_SLACK_USERNAME, LOG_SLACK_EMOJI	Condicional	Alertas via canal Slack do logger.
PAPERTRAIL_URL, PAPERTRAIL_PORT, LOG_PAPERTRAIL_HANDLER	Condicional	Envio ao Papertrail.
LOG_STDERR_FORMATTER, LOG_SYSLOG_FACILITY	Opcional	Formatação e syslog.
SQS_PREFIX, SQS_QUEUE, SQS_SUFFIX	Condicional	Somente se QUEUE_CONNECTION=sqs.
DYNAMODB_CACHE_TABLE, DYNAMODB_ENDPOINT	Condicional	Somente se cache DynamoDB.
MEMCACHED_HOST, MEMCACHED_PORT, MEMCACHED_USERNAME, MEMCACHED_PASSWORD, MEMCACHED_PERSISTENT_ID	Condicional	Somente se cache Memcached.

Variáveis disponíveis fora do .env.example

O framework consulta outras variáveis que não aparecem no arquivo de exemplo porque pertencem a drivers alternativos ou ajustes avançados. Elas são opcionais/condicionais, não itens ausentes da implantação padrão:

Grupo	Variáveis	Quando usar
Autenticação	AUTH_GUARD, AUTH_MODEL, AUTH_PASSWORD_BROKER, AUTH_PASSWORD_RESET_TOKEN_TABLE, AUTH_PASSWORD_TIMEOUT	Somente ao personalizar os padrões de autenticação.
Banco genérico	DB_COLLATION, DB_FOREIGN_KEYS, DB_SOCKET, MYSQL_ATTR_SSL_CA	Somente no driver que oferece a opção. DB_ENCRYPT e DB_TRUST_SERVER_CERTIFICATE estão apenas como exemplos comentados para SQL Server.
Cache em banco	DB_CACHE_CONNECTION, DB_CACHE_TABLE, DB_CACHE_LOCK_CONNECTION, DB_CACHE_LOCK_TABLE	Quando CACHE_STORE=database.
Fila em banco	DB_QUEUE_CONNECTION, DB_QUEUE_TABLE, DB_QUEUE, DB_QUEUE_RETRY_AFTER	Quando QUEUE_CONNECTION=database.
Beanstalkd	BEANSTALKD_QUEUE_HOST, BEANSTALKD_QUEUE, BEANSTALKD_QUEUE_RETRY_AFTER	Somente com esse driver de fila.
Redis avançado	REDIS_CLUSTER, REDIS_CACHE_CONNECTION, REDIS_CACHE_LOCK_CONNECTION	Cluster ou conexões nomeadas diferentes.
Sessão avançada	SESSION_CONNECTION, SESSION_TABLE, SESSION_STORE	Driver de sessão que exige conexão/tabela/store explícito.
Broadcasting alternativo	PUSHER_APP_ID, PUSHER_APP_KEY, PUSHER_APP_SECRET, PUSHER_APP_CLUSTER, PUSHER_HOST, PUSHER_PORT, PUSHER_SCHEME, ABLY_KEY	Somente ao substituir Reverb.
Slack como serviço	SLACK_BOT_USER_OAUTH_TOKEN, SLACK_BOT_USER_DEFAULT_CHANNEL	Integração de notificação do framework, não WhatsApp.
Postmark	POSTMARK_MESSAGE_STREAM_ID	A configuração atual o mantém comentado; habilite apenas junto com o driver.

BCRYPT_ROUNDS e as variáveis VITE_* aparecem no .env.example, embora sejam consumidas respectivamente pela configuração de hashing e diretamente pelo build frontend, não pela busca simples em config/.

Aplicar e validar

1. Salve as variáveis no mecanismo seguro do ambiente.
2. Limpe e reconstrua o cache de configuração na etapa de deploy.
3. Recompile assets quando uma variável VITE_* mudar.
4. Reinicie web, worker, scheduler e Reverb graciosamente.
5. Execute os checklists de Ambientes e infraestrutura e Diagnóstico.

Nunca cole a saída completa de php artisan about, env, logs ou painel de hospedagem em um canal público; ela pode conter endpoints e dados operacionais.