asin
Returns the arc sine of a number in radians, the inverse of sin().
asin(float $num): float- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$num | float | The argument to process. Values outside the range -1 to 1 produce NAN. |
Return value
floatThe arc sine of num in radians, in the range -PI/2 to PI/2. Returns NAN when num is outside -1 to 1.
Errors
Throws a TypeError if num cannot be coerced to float. Out-of-domain values return NAN instead of throwing.
asin() takes a sine value and returns the angle that produced it, in radians between -M_PI/2 and M_PI/2 (-90 to 90 degrees). It is the inverse of sin().
When to reach for it
Reach for asin() whenever you have a ratio of "opposite over hypotenuse" and want the angle: the incline of a ramp from its rise and its sloped length, the elevation of the sun from a normalised height, the tilt of a device from a normalised accelerometer axis.
Its most-used appearance in web code is the haversine formula for distance between two latitude/longitude pairs, where the final step is 2 * $earthRadius * asin(sqrt($h)). That form is preferred over the acos() version because it stays numerically accurate for points that are very close together.
What trips people up
The domain is -1 to 1 and nothing else. A ratio computed from measured data can drift to 1.0000000001 and asin() will hand back NAN with no warning, which then spreads through every later calculation. Clamp before calling.
The output range only covers two quadrants, so asin() cannot distinguish an angle of 150 degrees from one of 30 degrees — both have the same sine. When you need a full-circle angle, compute it with atan2() instead.
Example
When to use it
- Compute the angle of a wheelchair ramp from its rise and sloped length.
- Finish a haversine great-circle distance calculation between two coordinates.
- Convert a normalised accelerometer reading into a device tilt angle.
Frequently asked questions
What is the difference between asin() and atan2()?
asin() only sees a single ratio, so it can only return angles between -90 and 90 degrees. atan2() takes the two components separately and uses their signs to return the correct angle anywhere in the full circle.
Why does asin(2) return NAN?
Because no angle has a sine of 2 — sine values only ever run from -1 to 1. PHP reports the out-of-domain input as NAN rather than throwing an error.
How do I convert the result of asin() to degrees?
Wrap it in rad2deg(), for example rad2deg(asin(0.5)) gives 30. Every PHP trigonometric function works in radians.
More examples
Haversine distance between two cities
The output is 877 km, the great-circle distance from Berlin to Paris. asin() is what converts the haversine intermediate value into the central angle that is then scaled by the Earth's radius.
<?php
$lat1 = deg2rad(52.5200); $lon1 = deg2rad(13.4050); // Berlin
$lat2 = deg2rad(48.8566); $lon2 = deg2rad(2.3522); // Paris
$h = sin(($lat2 - $lat1) / 2) ** 2
+ cos($lat1) * cos($lat2) * sin(($lon2 - $lon1) / 2) ** 2;
$km = 2 * 6371 * asin(sqrt($h));
echo round($km), " km", PHP_EOL;Ramp angle from rise and length
A 0.5 m rise over a 6 m slope gives 4.78 degrees, comfortably inside the usual accessibility limit, and the second line prints the same slope as the 1:12 gradient builders quote.
<?php
$rise = 0.5; // metres
$length = 6.0; // sloped length in metres
$angle = rad2deg(asin($rise / $length));
printf("%.2f degrees\n", $angle);
printf("gradient 1:%.1f\n", $length / $rise);
Discussion