Função PHP inet_ntop(): Tudo o que Você Precisa Saber

A função inet_ntop() converte um endereço IP binário compactado em uma string legível por humanos. O nome significa "network to presentation" (rede para apresentação): ela recebe a forma compacta e de tamanho fixo que um endereço IP possui na memória (ou em uma coluna de banco de dados) e o converte de volta para a notação decimal com pontos (127.0.0.1) ou hexadecimal com dois-pontos (::1), que você consegue ler e registrar em logs.

Esta página explica o que é o formato compactado, como usar inet_ntop() tanto para IPv4 quanto para IPv6, como ela se complementa com inet_pton(), como lidar com erros e quando é a escolha certa utilizá-la.

Por que existe um formato "compactado"

Um endereço IPv4 como 192.168.1.1 é apenas 32 bits — quatro bytes. Um endereço IPv6 tem 128 bits — dezesseis bytes. O texto legível que você normalmente vê é uma apresentação desses bytes, não os bytes em si.

Quando você armazena ou compara endereços em escala, os bytes brutos são menores e mais rápidos: uma coluna VARBINARY(16) armazena qualquer endereço IPv4 ou IPv6, ordena corretamente e indexa bem. inet_pton() produz essa forma compactada; inet_ntop() a reverte para que humanos possam lê-la novamente.

"127.0.0.1"  --inet_pton()-->  \x7f\x00\x00\x01   (4 packed bytes)
\x7f\x00\x00\x01  --inet_ntop()-->  "127.0.0.1"   (readable text)

Sintaxe

inet_ntop(string $ip): string|false

A função recebe um único parâmetro:

• $ip — uma string binária contendo o endereço compactado. Deve ter exatamente 4 bytes para IPv4 ou 16 bytes para IPv6.

Ela retorna o endereço como uma string legível, ou false se a entrada não for um endereço compactado válido de 4 ou 16 bytes.

Convertendo um endereço IPv4

Um endereço IPv4 compactado tem quatro bytes brutos, um por octeto. O endereço de loopback 127.0.0.1 é, portanto, \x7f (127), \x00, \x00, \x01:

Escrever sequências de escape manualmente é suscetível a erros. Na prática, você obtém os bytes compactados de inet_pton() ou de um banco de dados e os passa diretamente para inet_ntop():

<?php

$packed = inet_pton("192.168.1.1"); // text -> 4 packed bytes
echo inet_ntop($packed);            // Outputs: 192.168.1.1

Convertendo um endereço IPv6

A mesma função lida com IPv6 — passe uma string compactada de 16 bytes e ela retorna a forma hexadecimal comprimida com dois-pontos, recolhendo automaticamente sequências de zeros para :::

<?php

$packed = inet_pton("2001:db8::1");
echo inet_ntop($packed); // Outputs: 2001:db8::1

Como uma única função abrange ambas as famílias, você pode fazer a conversão de ida e volta de qualquer endereço sem ramificar pelo tipo — útil quando uma coluna pode conter qualquer um dos tipos.

Lidando com entrada inválida

Se a string binária não tiver exatamente 4 ou 16 bytes, inet_ntop() retorna false e emite um aviso. Sempre verifique o resultado antes de usá-lo:

<?php

$result = inet_ntop("not a packed address");

if ($result === false) {
    echo "Invalid packed address.";
} else {
    echo $result;
}
// Outputs: Invalid packed address.

Use uma comparação estrita === false: uma verificação mais fraca também rejeitaria "0.0.0.0", que é um endereço válido.

inet_ntop() vs. ip2long()

Para IPv4, você também pode encontrar long2ip(), que converte um inteiro de 32 bits de volta para uma string decimal com pontos. A diferença:

• ip2long() / long2ip() trabalham com uma representação inteira e são exclusivos para IPv4.
• inet_pton() / inet_ntop() trabalham com uma string binária e suportam tanto IPv4 quanto IPv6.

Se sua aplicação precisar lidar com IPv6, prefira o par inet_* para que um único caminho de código sirva a todos os endereços.

Quando usar

• Lendo endereços de volta do armazenamento — uma coluna VARBINARY(16) armazena qualquer endereço de forma compacta; inet_ntop() renderiza as linhas para exibição ou registro em logs.
• Normalizando entrada do usuário — converter de ida e volta com inet_pton() e depois inet_ntop() produz uma forma canônica (por exemplo, 2001:0db8::0001 se torna 2001:db8::1), de modo que endereços iguais se comparam como strings iguais.
• Trabalhando com dados brutos de socket — endereços compactados retornados por chamadas de rede de baixo nível se tornam legíveis para logs e mensagens de erro.

Funções relacionadas

• inet_pton() — o inverso: endereço legível para string binária compactada.
• ip2long() — string IPv4 para inteiro.
• long2ip() — inteiro de volta para uma string IPv4.
• gethostbyname() — resolve um hostname para seu endereço IPv4.

Conclusão

inet_ntop() converte um endereço IP compactado de 4 ou 16 bytes de volta em texto legível tanto para IPv4 quanto para IPv6, complementando inet_pton(). Armazene endereços em sua forma binária compacta para indexação eficiente, converta-os com inet_ntop() quando precisar exibi-los ou registrá-los em logs, e sempre verifique se há um retorno false para entradas malformadas.

Prática