atan2()

A função atan2() no PHP calcula o arco tangente de dois números, $y e $x. Ela retorna o ângulo (em radianos) entre o eixo x positivo e o ponto ($x, $y), o que é exatamente o que você precisa quando deseja converter um par de coordenadas de volta em uma direção.

Esta página cobre a sintaxe da função, o que ela retorna, a diferença fundamental entre atan2() e atan(), e exemplos executáveis.

O que é a Função atan2()?

atan2() é uma função matemática embutida que retorna o arco tangente do quociente $y / $x, mas — de forma crucial — ela usa os sinais de ambos os argumentos para posicionar o resultado no quadrante correto. O resultado é expresso em radianos e varia de -π a π (aproximadamente -3.14159 a 3.14159).

Sintaxe

atan2(float $y, float $x): float

Parâmetros

Valor de retorno

Um float no intervalo -π a π representando o ângulo em radianos. Converta para graus com rad2deg() quando precisar de um ângulo legível por humanos.

atan2() vs atan()

A função de argumento único atan() enxerga apenas $y / $x como um único número, portanto não consegue distinguir, por exemplo, (1, 1) de (-1, -1) — ambos resultam em uma razão de 1. Ela sempre retorna um ângulo entre -π/2 e π/2 e descarta o quadrante. Também pode se comportar de forma incorreta quando $x é 0, pois isso seria uma divisão por zero.

atan2($y, $x) mantém ambos os sinais, cobrindo o círculo completo (-π a π) e tratando com segurança o caso $x = 0. Use atan2() sempre que suas entradas forem coordenadas reais em vez de uma razão pré-calculada.

Como Usar a Função atan2()

Passe o valor y primeiro, depois o valor x, e converta o resultado em radianos para graus se necessário:

Isso imprime:

Radians: 1.1071487177941
Degrees: 63.434948822922

Definimos $y e $x, passamos para atan2() para obter o ângulo em radianos e, em seguida, usamos rad2deg() para converter esse resultado em graus.

Tratamento de Quadrantes

Este exemplo mostra como atan2() retorna um ângulo distinto para pontos em quadrantes diferentes — mesmo quando a razão $y / $x é a mesma:

<?php
// Same ratio (1), but different quadrants
echo rad2deg(atan2(1, 1)), "\n";   // upper-right quadrant
echo rad2deg(atan2(-1, -1)), "\n"; // lower-left quadrant

// $x is zero — no division-by-zero error
echo rad2deg(atan2(1, 0)), "\n";   // straight up
?>

Saída:

45
-135
90

Como atan2() inspeciona ambos os sinais, os pontos (1, 1) e (-1, -1) mapeiam para 45° e -135° respectivamente, e um $x zero é tratado sem problemas.

Conclusão

atan2() é a função ideal para converter um par de coordenadas em um ângulo no PHP. Ela retorna radianos no intervalo -π a π, resolve corretamente todos os quatro quadrantes e evita problemas de divisão por zero que afetam o atan() de argumento único. Para trigonometria relacionada, consulte atan(), tan() e os auxiliares de conversão deg2rad() / rad2deg().

Prática