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

A função PHP inet_pton() converte um endereço IP legível por humanos — como 127.0.0.1 ou 2001:db8::1 — para sua representação binária compactada. O nome significa "presentation to network" (apresentação para rede): ela recebe a forma de apresentação (o texto com pontos/dois-pontos que você digita) e retorna a forma de rede (os bytes brutos que realmente trafegam na rede).

Esta página aborda a sintaxe, tanto IPv4 quanto IPv6, como ler o resultado com segurança, como revertê-lo e as razões práticas para armazenar IPs em formato binário.

O que é a função inet_pton()?

inet_pton() analisa uma string IPv4 ou IPv6 válida e retorna uma string binária compactada in-addr — 4 bytes para IPv4, 16 bytes para IPv6. Se a entrada não for um endereço IP válido, ela retorna false em vez de lançar uma exceção.

A "string binária" retornada não é legível por humanos: são os bytes brutos, então imprimi-la diretamente em um terminal ou navegador exibe caracteres ininteligíveis. Para inspecioná-la, converta-a com bin2hex(). Para transformá-la de volta em uma string IP normal, use sua função espelho, inet_ntop().

Sintaxe

inet_pton(string $ip): string|false

A função recebe um parâmetro:

• $ip — o endereço IP a ser convertido, como uma string (IPv4 ou IPv6).

Valor de retorno: a string binária compactada em caso de sucesso, ou false se $ip não for um endereço IP válido.

Exemplo básico: IPv4

Os 4 bytes brutos de 127.0.0.1 são 7f 00 00 01 — exatamente os octetos decimais de 127.0.0.1 escritos em hexadecimal. Como a string binária em si não é imprimível, a passamos por bin2hex() para que os bytes apareçam como hex legível.

IPv4 e IPv6

Ao contrário da função mais antiga ip2long(), que só lida com IPv4, inet_pton() funciona com ambas as famílias de endereços. IPv4 produz 4 bytes; IPv6 produz 16:

<?php

echo bin2hex(inet_pton("192.168.1.1")), "\n";   // c0a80101  (4 bytes)
echo bin2hex(inet_pton("2001:db8::1")), "\n";    // 20010db8000000000000000000000001 (16 bytes)

echo strlen(inet_pton("192.168.1.1")), "\n";     // 4
echo strlen(inet_pton("2001:db8::1")), "\n";     // 16

Verificar strlen() no resultado é a forma mais simples de determinar a qual família um endereço pertence: um comprimento de 4 significa IPv4, 16 significa IPv6.

Tratando entradas inválidas

Quando a string não é um IP válido, inet_pton() retorna false. Sempre verifique o resultado antes de usá-lo — caso contrário, você pode acabar armazenando ou comparando false (uma string vazia) por acidente:

<?php

$input = "not-an-ip";
$packed = inet_pton($input);

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

Use comparação estrita (===) aqui. Um 0.0.0.0 válido é compactado como o byte 00000000, cujo primeiro byte é um byte nulo; uma verificação solta com == false pode disparar incorretamente em casos extremos, então === false é o teste seguro.

Revertendo a conversão

inet_pton() e inet_ntop() formam um par complementar: uma compacta, a outra descompacta. Uma ida e volta retorna o endereço original:

<?php

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

Quando eu usaria isso?

Armazenar IPs como binário compactado é principalmente sobre armazenamento compacto, ordenável e independente de família:

• Armazenamento em banco de dados. Uma coluna binária (VARBINARY(16)) armazena qualquer endereço IPv4 ou IPv6 em um formato fixo e compacto, e ordena corretamente. Use inet_pton() antes do INSERT e inet_ntop() após o SELECT.
• Comparações de intervalos. Como os bytes preservam a ordem numérica, você pode comparar strings compactadas para verificar se um endereço está dentro de uma sub-rede.
• Buscas por correspondência exata. Comparar chaves binárias de comprimento fixo é mais rápido e evita a ambiguidade das formas textuais (por exemplo, 2001:db8::1 e 2001:0db8:0000:...:0001 são o mesmo endereço, mas strings diferentes — a compactação os normaliza).

Para cálculos numéricos somente com IPv4, ip2long() e long2ip() são uma alternativa, mas não conseguem representar IPv6.

Conclusão

inet_pton() converte um endereço IPv4 ou IPv6 de sua forma textual legível por humanos para uma string binária compactada — 4 bytes para IPv4, 16 para IPv6 — e retorna false para entradas inválidas. Use-a em conjunto com inet_ntop() para reverter a conversão, e use bin2hex() quando precisar inspecionar os bytes brutos. É a forma padrão de armazenar e comparar endereços IP de forma compacta em um banco de dados, suportando ambas as famílias de endereços.

Prática