finally

A Palavra-chave PHP "finally": Um Guia Completo

A palavra-chave finally faz parte da sintaxe de tratamento de exceções do PHP. Um bloco finally é anexado a uma instrução try e tem execução garantida após o bloco try (e qualquer bloco catch correspondente) — seja o código bem-sucedido, tenha lançado uma Exception ou retornado antecipadamente. Essa garantia o torna o lugar certo para trabalhos de limpeza: fechar arquivos, liberar bloqueios, encerrar transações de banco de dados ou registrar logs.

Esta página aborda a sintaxe, a ordem exata em que os blocos são executados, como o finally interage com o return e os padrões comuns onde você realmente precisa dele.

Sintaxe

O bloco finally é anexado a uma instrução try e é executado após os blocos try e quaisquer blocos catch, independentemente de uma exceção ter sido lançada ou tratada. Aqui está a sintaxe básica para usar a palavra-chave finally em PHP:

A sintaxe PHP do finally

try {
  // code to be executed
} catch (Exception $e) {
  // code to handle the exception
} finally {
  // code to be executed regardless of whether an exception was thrown or caught
}

O bloco catch é opcional quando um bloco finally está presente — try ... finally (sem catch) é PHP válido. Nesse caso, o bloco finally ainda é executado, mas qualquer exceção permanece não capturada e se propaga para cima após o finally terminar.

Como os blocos são executados

A ordem é sempre a mesma:

1. O bloco try é executado.
2. Se uma exceção for lançada, o primeiro bloco catch correspondente é executado. Se nenhum corresponder, a exceção é mantida para ser relançada.
3. O bloco finally é executado — sempre.
4. O controle sai da instrução (retornando um valor ou relançando uma exceção não capturada).

Este pequeno script torna a ordem visível:

<?php

function demo(bool $fail): void
{
  try {
    echo "1. try\n";
    if ($fail) {
      throw new Exception("boom");
    }
  } catch (Exception $e) {
    echo "2. catch: {$e->getMessage()}\n";
  } finally {
    echo "3. finally\n";
  }
  echo "4. after\n";
}

demo(false);
echo "---\n";
demo(true);

// Output:
// 1. try
// 3. finally
// 4. after
// ---
// 1. try
// 2. catch: boom
// 3. finally
// 4. after

Observe que finally é executado nos dois casos — uma vez sem exceção e uma vez após o catch.

Exemplos

Vejamos alguns exemplos práticos de como a palavra-chave finally pode ser usada:

Exemplos de finally em PHP

<?php

// Example 1
function divide($a, $b)
{
  try {
    if ($b == 0) {
      throw new Exception("Division by zero.");
    }
    return $a / $b;
  } catch (Exception $e) {
    echo "Error: " . $e->getMessage();
  } finally {
    echo "This code will always be executed.";
  }
}

divide(10, 0);

// Output: Error: Division by zero.This code will always be executed.

// Example 2
$file = "example.txt";
$handle = fopen($file, "r");
try {
  if (!$handle) {
    throw new Exception("Unable to open file.");
  }
  // code to be executed
} catch (Exception $e) {
  echo "Error: " . $e->getMessage();
} finally {
  if ($handle !== false) {
    fclose($handle);
  }
}

// Output: Error: Unable to open file.

Nestes exemplos, usamos a palavra-chave finally para garantir que o código de limpeza ou registro de logs seja executado de forma consistente.

finally e return

Um bloco finally é executado mesmo quando try ou catch contém um return. O PHP avalia o valor de retorno, executa o finally e então retorna de fato. Se o próprio bloco finally retornar um valor, esse valor substitui o anterior — uma fonte sutil de bugs, portanto evite retornar a partir do finally.

<?php

function withReturn(): string
{
  try {
    return "from try";
  } finally {
    echo "finally still runs\n";
  }
}

function overriding(): string
{
  try {
    return "from try";
  } finally {
    return "from finally"; // overrides the try return
  }
}

echo withReturn() . "\n";
echo overriding() . "\n";

// Output:
// finally still runs
// from try
// from finally

A mesma regra de substituição se aplica a exceções: se finally lançar uma exceção, ela substituirá qualquer exceção ou valor de retorno que estava pendente em try/catch.

Benefícios

O uso da palavra-chave finally traz vários benefícios, incluindo:

• Melhor tratamento de erros: garante que o código essencial de limpeza ou registro de logs seja executado de forma consistente, mesmo quando exceções ocorrem ou são tratadas.
• Código simplificado: elimina a necessidade de duplicar a lógica de fechamento de recursos em múltiplos blocos catch ou caminhos de erro.

Conclusão

Em resumo, a palavra-chave finally fornece uma maneira confiável de executar código essencial de limpeza durante o tratamento de exceções — fechar recursos, liberar bloqueios e registrar logs — independentemente de uma exceção ter sido lançada. Use-a sempre que um recurso aberto em try precisar ser liberado de qualquer forma, e evite usar return em um bloco finally para não engolir acidentalmente um resultado ou uma exceção.

Para se aprofundar no tratamento de erros em PHP, consulte try, catch, a classe Exception e o guia completo de exceções em PHP.

Prática