atan2
Returns the arc tangent of y/x in radians, using both signs to pick the correct quadrant.
atan2(float $y, float $x): float- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$y | float | Dividend parameter — the vertical component. |
$x | float | Divisor parameter — the horizontal component. |
Return value
floatThe arc tangent of y/x in radians, between -PI and PI inclusive.
Errors
Throws a TypeError if either argument cannot be coerced to float. It does not raise a division-by-zero error when x is 0.
atan2() converts a pair of coordinates into the angle of the vector they describe. It is the quadrant-aware version of atan(): because it receives y and x separately it can see both signs, so it returns an angle covering the whole circle, from -M_PI to M_PI.
When to reach for it
Any time you have a displacement and want a direction. Bearings between two map points, the rotation needed to point a sprite at the cursor, the phase of a complex number, the direction of a wind vector from its north and east components, the angle of a line for an SVG label. Pair it with hypot() and you have full conversion from Cartesian to polar coordinates in two calls.
It is also the safe choice numerically: atan2($y, 0) returns ±M_PI/2 instead of raising a division-by-zero error, and atan2(0, 0) returns 0.
What trips people up
The argument order is (y, x), the reverse of how coordinates are usually written and the reverse of a spreadsheet's ATAN2. Swapping them mirrors every angle about the 45-degree line, and the bug is easy to miss because the results still look plausible.
Results are signed. To get a 0-360 compass bearing, add a full turn and take the remainder: fmod(rad2deg(atan2($e, $n)) + 360, 360).
Example
When to use it
- Compute the compass bearing from one map point to another.
- Rotate a game sprite or canvas element to face a target position.
- Convert an x/y wind or force vector into a direction and magnitude alongside hypot().
Frequently asked questions
Is atan2 (x, y) or (y, x) in PHP?
It is atan2($y, $x) — the vertical component first. This is the same order as C and JavaScript, but the reverse of Excel's ATAN2, which is a common source of ported-formula bugs.
What does atan2(0, 0) return?
It returns 0. There is no meaningful direction for a zero-length vector, so PHP picks 0 rather than raising an error.
How do I get a 0 to 360 degree angle from atan2()?
atan2() returns -180 to 180 degrees after rad2deg(), so add 360 and take the remainder: fmod(rad2deg(atan2($y, $x)) + 360, 360).
More examples
Compass bearing normalised to 0-360
Moving east and south gives a bearing of 116.6 degrees, in the south-east quadrant as expected. Note the arguments are (east, north) here because for compass bearings north plays the role of x — the reference axis you measure from.
<?php
$east = 500.0; // metres east
$north = -250.0; // metres south
$bearing = fmod(rad2deg(atan2($east, $north)) + 360, 360);
printf("bearing %.1f degrees\n", $bearing);
printf("distance %.1f m\n", hypot($east, $north));Cartesian to polar and back
The point (-3, 4) has radius 5 and an angle of 126.87 degrees, correctly placed in the second quadrant. The last line rebuilds the original coordinates with cos() and sin(), confirming the round trip.
<?php
$x = -3.0;
$y = 4.0;
$r = hypot($x, $y);
$theta = atan2($y, $x);
printf("r=%.1f theta=%.4f rad (%.2f deg)\n", $r, $theta, rad2deg($theta));
printf("back: x=%.1f y=%.1f\n", $r * cos($theta), $r * sin($theta));
Discussion