Ciclo do pedido e configuração

Versão e fronteira do percurso

Este percurso usa Laravel 13.x e pressupõe conhecimentos de PHP: classes, interfaces, tipos, exceções e Composer. O framework exige pelo menos PHP 8.3; isso não prova que uma aplicação e todos os seus pacotes aceitem qualquer versão posterior.

Antes de uma mudança real, o contrato do projeto e as dependências concretas também contam. Aqui analisamos decisões do framework através de excertos e cenários, com avaliação exclusivamente por escolha de respostas.

Entrada pública e ficheiros internos

A configuração do servidor deve encaminhar os pedidos da aplicação para public/index.php. Esse ficheiro carrega o autoloader do Composer e obtém a aplicação a partir de bootstrap/app.php. Publicar a raiz do projeto para contornar uma rota que falha expõe uma área excessiva: desativar a listagem de diretórios não bloqueia pedidos diretos a nomes conhecidos.

Mantém os ficheiros internos fora da raiz pública e diagnostica separadamente o encaminhamento do servidor e o router da aplicação.

Do arranque à resposta

O arranque prepara ambiente, logs, tratamento de erros e providers. O pedido atravessa middleware e chega à rota correspondente se os controlos anteriores o permitirem. Um middleware pode devolver uma resposta sem chamar o próximo componente; nesse caso, a ausência de execução do controller é esperada.

Quando o controller devolve uma resposta, esta volta a atravessar a cadeia de middleware. Localiza a última fase observada antes de atribuir a falha ao código de negócio.

Um valor e três representações

Distingue o valor escrito em .env, a variável externa entregue ao processo e a entrada que a aplicação lê em config. Variáveis externas podem prevalecer sobre o ficheiro. No exemplo, env é usado na definição de configuração e config é usado no serviço.

A chave services.invoice.endpoint identifica o ficheiro services e as chaves internas; não inclui o nome da pasta config. Esta separação permite discutir valores efetivos sem espalhar leituras de ficheiros pelo código de negócio.

Cache e mudança de destino

config:cache reúne os valores de configuração num artefacto carregável. Depois disso, Laravel não carrega .env nos pedidos ou comandos Artisan; env ainda pode devolver variáveis externas. Por isso, não concluas que env fica sempre inutilizável, nem dependas dele em serviços que esperam valores apenas do ficheiro.

No cenário A para B, a correção é reconstruir a configuração com as entradas autorizadas e observar a nova execução. Reiniciar um processo sem alterar uma cache antiga pode continuar a carregar A.

Operação sem publicar segredos

Um .env.example com valores fictícios comunica as entradas esperadas. Um .env real em claro pode expor credenciais mesmo num repositório privado; a entrega dos segredos deve ter controlo próprio. Em produção, confirma que app.debug está efetivamente desativado, incluindo a cache em uso.

Para escritas da aplicação, ajusta a identidade do processo e o acesso necessário a storage e bootstrap/cache. Dar escrita universal ao projeto inteiro não é uma resposta proporcional a um erro de logs.

O que um 200 demonstra

Sem extensões, o endpoint de saúde /up indica que a aplicação arrancou sem exceção nesse pedido. Não demonstra que a base de dados, uma integração de faturação ou uma transação de pagamento estejam operacionais. Um listener de DiagnosingHealth permite acrescentar checks, mas o desenho deve explicitar o que observa e limitar o custo e o tempo.

No caso proposto, o 200 e a falha de pagamento podem coexistir: o problema está em usar um sinal de arranque como se cobrisse a dependência necessária à admissão.

Armadilhas comuns

Servir a raiz do projeto; chamar env dentro de ações dependentes de dotenv; presumir que editar .env invalida a cache; ativar debug em produção; interpretar /up como teste automático de todas as dependências.