die()

O que a Função die() Faz

A função die() interrompe o script PHP exatamente onde é chamada. Nada após ela é executado — nenhuma instrução adicional, nenhuma saída posterior, nenhum loop restante. Opcionalmente, ela imprime uma mensagem (ou retorna um código de status) no momento em que para.

die() é um alias de exit(): os dois são completamente intercambiáveis, aceitam o mesmo argumento e se comportam de forma idêntica. O PHP mantém ambos os nomes porque die se lê naturalmente em código de "parar em caso de erro" (... or die(...)) enquanto exit se lê naturalmente quando você simplesmente deseja encerrar um script. Use o que tornar o código ao redor mais claro; esta página usa die() ao longo de todo o texto.

Sintaxe

die(string $message = "")
die(int $status = 0)

die() aceita um argumento opcional, e o que você passa muda seu comportamento:

• Uma string — o PHP imprime essa string e, em seguida, encerra. Este é o caso mais comum.
• Um integer — o PHP encerra com esse valor como o status de saída e não imprime nada. 0 significa sucesso; 1–254 sinalizam um erro para o shell. Isso importa apenas para scripts de linha de comando (php script.php), onde outro programa lê $? para saber se o script foi bem-sucedido.
• Nada — o script simplesmente termina, sem saída e com um status de saída de 0.

die() é um construto de linguagem, não uma função regular, portanto os parênteses são opcionais (die; é válido). Incluí-los mantém o código consistente com chamadas de função normais.

Interrompendo um Script em uma Condição com Falha

O uso mais frequente de die() é sair no momento em que algo está errado, para que o restante do script nunca seja executado com dados incorretos:

Como $name não é "Jane", o corpo do if é executado, die() imprime Access denied!, e o script termina imediatamente — a linha echo nunca é alcançada. Se $name fosse "Jane", die() seria ignorada e o script imprimiria Welcome, Jane! em vez disso.

O Idioma "or die()"

die() é frequentemente encadeada a uma expressão com or. O PHP avalia o lado esquerdo primeiro; somente se ele for falsy (como false ou null) é que ele avança e executa die(). Esta é a forma clássica de proteger uma operação que pode falhar:

<?php

$file = fopen("missing-config.txt", "r") or die("Could not open the config file.");

echo "File opened successfully.";

Se fopen() for bem-sucedida, ela retorna um identificador de arquivo (truthy), portanto or die(...) nunca é alcançado. Se o arquivo estiver ausente, fopen() retorna false, die() é executada e o script para antes do echo.

Esse idioma é conciso, mas no código moderno prefira o tratamento real de erros — lançar uma exceção ou registrar por meio de error_log() — para que as falhas possam ser capturadas e relatadas em vez de matar abruptamente a requisição. Veja trigger_error() e relatório de erros para alternativas mais limpas.

Status de Saída para Scripts de Linha de Comando

Quando você executa PHP a partir do terminal, o status de saída informa ao shell ou pipeline de CI que invocou se o script funcionou:

<?php

$ok = false;

if (!$ok) {
  fwrite(STDERR, "Job failed\n"); // write the message yourself...
  die(1);                         // ...then exit with a non-zero status
}

die(0); // success

Passar um integer para die() define o status, mas não imprime nada, portanto escreva qualquer mensagem legível por humanos você mesmo (aqui para STDERR) antes de sair. Um script externo pode então verificar $? e reagir ao 1.

Armadilhas

• die() não ignora nenhuma limpeza que você registrou com register_shutdown_function() — callbacks de encerramento e destrutores de objetos ainda são executados. Mas o código escrito após a chamada die() nunca é executado.
• Em uma requisição web, die() encerra toda a resposta. A saída já enviada ao navegador permanece; tudo que está enfileirado após a chamada é descartado. Evite-a dentro de funções destinadas a ser reutilizáveis — retorne um valor ou lance uma exceção em vez disso.
• Um argumento integer não imprime nada. die(1) não exibe 1; se você quiser que o usuário veja uma mensagem, passe uma string ou imprima-a antes de chamar die().
• Prefira exceções no código de aplicação. die() não pode ser capturada, testada facilmente ou recuperada. Reserve-a para scripts de nível superior e diagnósticos rápidos.

Conclusão

die() (e seu equivalente exit()) encerra um script PHP no local, opcionalmente imprimindo uma mensagem ou definindo um status de saída. É ideal para proteções rápidas em scripts standalone e de linha de comando, mas para a lógica de aplicação em produção, use exceções e o tratamento de erros adequado para que as falhas permaneçam capturáveis. Para aprofundar-se na escrita e estruturação de código que a chama, veja funções PHP.

Prática