asin()

Purpose

asin() calculates the arc sine of a number. In other words, it answers the question: which angle has this sine? The result is an angle measured in radians, not degrees. It is the inverse of sin() for values that fall inside the function's domain.

Typical uses include recovering an angle from a ratio of two lengths (opposite side divided by hypotenuse), working with slopes and ramps, and converting normalized sensor or geometry values back to angles.

Signature

Parameters and defaults

• $num: the value whose arc sine you want. It has no default, so you must always pass it. The mathematically valid range is from -1 to 1 inclusive, because no real angle has a sine outside that interval.

Integers are accepted and converted to float. In the default (non-strict) typing mode, numeric strings are coerced as well, but relying on that makes code harder to read. Passing a non-numeric string or an array raises a TypeError.

Return value and failure cases

The function returns a float: the arc sine of $num in radians. For valid input the result lies between -M_PI / 2 and M_PI / 2, which is roughly -1.5708 to 1.5708.

If $num is outside -1 to 1, the function does not throw an exception. It returns NAN (not a number). Because NAN is never equal to anything, including itself, you must test for it with is_nan() rather than === or ==.

Example 1: values and degrees

The first example prints the arc sine of several well-known ratios. Since asin() gives radians, rad2deg() converts the result to degrees for readability. sprintf() fixes the number of decimals so floating-point noise does not affect the output.

<?php
foreach ([-1.0, -0.5, 0.0, 0.5, 1.0] as $x) {
    $rad = asin($x);
    echo sprintf("%.1f => %.4f rad, %.2f deg\n", $x, $rad, rad2deg($rad));
}

-1.0 => -1.5708 rad, -90.00 deg
-0.5 => -0.5236 rad, -30.00 deg
0.0 => 0.0000 rad, 0.00 deg
0.5 => 0.5236 rad, 30.00 deg
1.0 => 1.5708 rad, 90.00 deg

Example 2: out-of-range input and the round trip

Values beyond 1 or below -1 produce NAN. The same example shows that asin(sin($x)) only gives back $x when $x is within the principal range of the function. Here 2.0 radians is larger than M_PI / 2, so the result is a different angle with the same sine.

<?php
var_dump(asin(2));
var_dump(is_nan(asin(-1.5)));
echo sprintf("%.4f\n", asin(sin(2.0)));

float(NAN)
bool(true)
1.1416

Example 3: a ramp angle helper

A practical use is finding the angle of a ramp from its rise and its sloped length. The helper below guards against a non-positive length and against ratios outside the valid domain, returning null instead of letting NAN travel through your program.

<?php
function rampAngle(float $rise, float $length): ?float {
    if ($length <= 0) {
        return null;
    }
    $ratio = $rise / $length;
    if (abs($ratio) > 1) {
        return null;
    }
    return rad2deg(asin($ratio));
}

foreach ([[1.5, 6.0], [3.0, 6.0], [7.0, 6.0]] as [$rise, $length]) {
    $angle = rampAngle($rise, $length);
    echo $angle === null ? "invalid\n" : sprintf("%.2f\n", $angle);
}

14.48
30.00
invalid

Edge cases

• asin(0) is 0, asin(1) is M_PI / 2 and asin(-1) is -M_PI / 2.
• The function is odd: asin(-$x) equals -asin($x).
• Computed ratios can land slightly above 1 or below -1 because of floating-point rounding, for example 1.0000000000000002. That turns a perfectly sensible calculation into NAN. If you know the value is meant to be within range, clamp it with max(-1.0, min(1.0, $value)) before calling asin().
• The result never covers a full circle. If you need an angle in all four quadrants from two coordinates, atan2() is usually the better tool.

Common mistakes

1. Treating the result as degrees. The return value is in radians. Convert with rad2deg() when you need degrees.
2. Passing degrees in. The argument is a sine value, not an angle. Passing 30 returns NAN, not 0.5.
3. Comparing with NAN. Use is_nan(); $result === NAN is never true.
4. Expecting a perfect round trip. asin(sin($x)) equals $x only for angles from -M_PI / 2 to M_PI / 2, and then only approximately because of floating-point precision.
5. Comparing floats exactly. Use rounding or a tolerance when checking results, as the examples do with sprintf().

Related functions

• sin() computes the sine and is the function asin() inverts.
• acos() returns the arc cosine.
• atan() returns the arc tangent.
• asinh() is the inverse hyperbolic sine, a different function despite the similar name.
• rad2deg() and deg2rad() convert between radians and degrees.
• is_nan() detects the NAN result.

Recap

asin(float $num): float returns the arc sine of a number in radians, between -M_PI / 2 and M_PI / 2. Valid input runs from -1 to 1; anything else yields NAN, which you detect with is_nan(). Convert to degrees with rad2deg(), clamp ratios that may drift out of range because of rounding, and remember that the function is the inverse of sin() only within its principal range.