ping

Este artigo aborda a função mysqli_ping() no PHP, que verifica se uma conexão com o servidor MySQL ainda está ativa e, quando suportado, reconecta de forma transparente um link interrompido. Você verá tanto a sintaxe orientada a objetos quanto a procedural, a assinatura da função, quando utilizá-la e a importante depreciação no PHP 8.4.

O que mysqli_ping() faz

mysqli_ping() verifica uma conexão MySQL ativa. Se a conexão estiver ativa, retorna true. Se o link estiver inativo, a função tenta reconectar quando a diretiva de configuração mysqli.reconnect está habilitada, retornando true em caso de reconexão bem-sucedida ou false se não puder ser restabelecida.

É mais útil em scripts de longa duração (workers, daemons, consumidores de fila) onde uma conexão pode ficar ociosa por tempo suficiente para o servidor encerrá-la após wait_timeout segundos — o clássico erro "MySQL server has gone away". Fazer o ping antes de uma consulta permite detectar ou recuperar essa situação.

Sintaxe

// Object-oriented style
$mysqli->ping(): bool

// Procedural style
mysqli_ping(mysqli $mysql): bool

Parâmetros

• $mysql (apenas procedural) — um identificador de link de conexão retornado por mysqli_connect() ou mysqli_init().

Valor de retorno — true se a conexão estiver ativa (ou tiver sido reconectada com sucesso), false caso contrário.

Nota de depreciação: mysqli_ping() e o recurso de reconexão automática estão depreciados a partir do PHP 8.4 e removidos em versões futuras, pois reconexões silenciosas podem perder estado de sessão (tabelas temporárias, instruções preparadas, transações, variáveis SET). A abordagem recomendada é capturar a falha na consulta e abrir uma nova conexão manualmente.

Exemplo orientado a objetos

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

// ping() automatically attempts to reconnect if the link is dead
if ($mysqli->ping()) {
    echo "Connection is OK!";
} else {
    echo "Error: " . $mysqli->error;
}

$mysqli->close();
?>

O script inicializa uma conexão MySQLi, verifica se ela foi bem-sucedida via connect_errno e, em seguida, chama ping() para confirmar que o link está ativo. Exibe uma mensagem de sucesso ou erro via connect_error conforme o resultado.

Nota de segurança: Em ambientes de produção, evite codificar credenciais de banco de dados diretamente no código. Use variáveis de ambiente ou arquivos de configuração seguros para armazenar dados sensíveis.

Exemplo procedural

Para o estilo procedural, você pode usar mysqli_ping($link) em vez disso:

<?php
$link = mysqli_connect("localhost", "username", "password", "database");

if (!$link) {
    die("Connection failed: " . mysqli_connect_error());
}

if (mysqli_ping($link)) {
    echo "Connection is OK!";
} else {
    echo "Error: " . mysqli_error($link);
}

mysqli_close($link);
?>

Alternativa moderna recomendada

Como ping() está depreciado no PHP 8.4, o padrão mais robusto é executar sua consulta, detectar a falha "gone away" e reconectar explicitamente:

<?php
function runWithReconnect(callable $makeConnection, string $sql): mysqli_result|bool
{
    $mysqli = $makeConnection();
    try {
        return $mysqli->query($sql);
    } catch (mysqli_sql_exception $e) {
        // MySQL error 2006: server has gone away — reopen and retry once.
        if ($e->getCode() === 2006) {
            $mysqli = $makeConnection();
            return $mysqli->query($sql);
        }
        throw $e;
    }
}
?>

Isso mantém você no controle total do estado da conexão em vez de depender de uma reconexão silenciosa.

Conclusão

mysqli_ping() é uma forma rápida de verificar se uma conexão MySQL ainda está ativa e, em versões mais antigas do PHP, de reconectar um link interrompido. É útil em scripts de longa duração, mas desde o PHP 8.4 está depreciado — prefira capturar a falha em query() e reabrir a conexão manualmente. Para mais informações sobre como estabelecer conexões, consulte mysqli_connect() e a visão geral do MySQLi.

Prática