A PHP support for string, decimal, radian and object angles, providing goniometric algebra and comparison between angles.

• Index
• Requirements
• Installation
• Quick Start
• Usage
  • Creating an angle
    • Degrees, minutes and seconds
    • String
    • Decimal (float)
    • Radian (float)
  • Getting angle values
    • Casting
      • To decimal (float)
      • To radian (float)
      • To string
  • Direction
  • Comparison
    • $\alpha \gt \beta$ (greater than)
    • $\alpha \ge \beta$ (greater than or equal)
    • $\alpha \lt \beta$ (less than)
    • $\alpha \le \beta$ (less than or equal)
    • $\alpha \cong \beta$ (equal)
    • $\alpha \ncong \beta$ (different)
  • Algebraic sum between two angles
• API documentation

• PHP v8.4+

composer require marcoconsiglio/goniometry

Import this class to represent angles.

use MarcoConsiglio\Goniometry\Angle;

Import this class to sum angles.

use MarcoConsiglio\Goniometry\Operations\Sum;

Create an Angle object.

$alfa = Angle::createFromValues(180, 30);
$beta = Angle::createFromString("180° 30'");
$gamma = Angle::createFromDecimal(180.5);
$delta = Angle::createFromRadian(M_PI); // 180°

This creates an angle from its values in degrees, minutes and seconds:

$alfa = Angle::createFromValues(180, 12, 43, Angle::CLOCKWISE); // 180° 12' 43"

Angle::COUNTERCLOCKWISE is the plus sign, Angle::CLOCKWISE is the minus sign.

The AngleOverflowException is thrown when you try to create an angle:

• with more than $\pm360^\circ$
• with more than $59'$
• with more than $59.\overline{9}''$.

This creates an angle from its textual representation:

$beta = Angle::createFromString("180° 12' 43\""); // Input from the user

This is possible thanks to the regular expressions

Angle::DEGREES_REGEX;
Angle::MINUTES_REGEX;
Angle::SECONDS_REGEX;

These regex expressions treat degrees and minutes as int type, but seconds are treated as a float type.

You can create a negative Angle if the string representation start with the minus (-) sign.

The NoMatchException is thrown when you try to create an angle:

• with more than $\pm360^\circ$
• with more than $59'$
• with more than $59.\overline{9}''$.

This create an angle from its decimal representation:

$gamma = Angle::createFromDecimal(180.2119); // 180.2119°

The AngleOverflowException is thrown when you try to create an Angle with more than $\pm360.0^{\circ}$.

This create an angle from its radian representation:

$delta = Angle::createFromRadian(M_PI); // deg2rad(M_PI) = 180°

The AngleOverflowException is thrown when you try to create an Angle with more than $\pm2\pi$.

You can obtain degrees values separated in an array (simple by default, or associative):

$values = $alfa->getDegrees();
echo $values[0]; // Degrees
echo $values[1]; // Minutes
echo $values[2]; // Seconds
$values = $alfa->getDegrees(true);
echo $value['degrees'];
echo $value['minutes'];
echo $value['seconds'];

There is read-only properties too:

$alfa->degrees;   // 180
$alfa->minutes;   // 12
$alfa->seconds;   // 43
$alfa->direction; // Angle::CLOCKWISE (1)

When the precision parameter is needed, you can obtain your maximum available precision with the PHP_FLOAT_DIG constant.

You can cast the angle to decimal, with optional precision:

$alfa->toDecimal(); // 180.2
$alfa->toDecimal(4); // 180.2119
$alfa->toDecimal(PHP_FLOAT_DIG) // 180.211971543295645

If the number of decimal places is not set, the casting operation preserve the original precision at the time the angle was built.

You can obtain a suggested precision to correctly represent the sexadecimal value of the Angle instance.

$precision = $alfa->suggested_decimal_precision;
$alfa->toDecimal($precision);

You can cast the angle to radian, with optional precision:

$alfa->toRadian(); // 3.1
$alfa->toRadian(3); // 3.141
$alfa->toRadian(PHP_FLOAT_DIG); // 3.141592653589793 

If the number of decimal places is not set, the casting operation preserve the original precision at the time the angle was built.

You can obtain the original precision to correctly represent the radian value of the Angle instance.

$precision = $alfa->original_radian_precision;
$alfa->toRadian($precision);

You can cast the angle to a string representation:

(string) $alfa; // 180° 30' 25.7"

In this case, maximum precision of seconds will be PHP_FLOAT_DIG.

Positive angles are represented by the class constant

Angle::COUNTER_CLOCKWISE; // 1

while negative angles are represented by the opposite class constant:

Angle::CLOCKWISE; // -1

You can toggle direction:

$beta = $alfa->toggleDirection();

Since the Angle instance is immutable, the toggleDirection() method returns a copy with the opposite sign.

You can check if an angle is clockwise or counterclockwise.

// If $alfa is a positive angle
$alfa->isCounterClockwise();    // true
$alfa->isClockwise();           // false
$beta->isCounterClockwise();    // false
$beta->isClockwise();           // true

You can compare an angle with a numeric value (not radian but decimal), numeric string or another Angle object. Comparisons are performed with absolute values (congruent comparison), meaning that $-90^\circ\cong+90^\circ$.

If you need a relative comparison, you should cast the angle to decimal and then perform the arithmetic comparison, meaning that $-90.0^\circ\lt+90.0^\circ$.

Each comparison can be performed using

• a string angle,
• an integer (sexagesimal degrees),
• a decimal (sexadecimal degrees),
• or another instance of Angle.

Comparisons via radian values ​​are not available.

You can specify an optional precision expressed as the number of decimal places used to round the angle value. The precision is only used when comparing to an integer, decimal (degrees), or another Angle object.

$alfa = Angle::createFromDecimal(179.999);
$alfa->isEqual(90, 0);  // true
$alfa->isEqual(90, 3);  // false

$alfa = Angle::createFromDecimal(180);
$beta = Angle::createFromDecimal(90);
$gamma = Angle::createFromDecimal(360);
$alfa->isGreaterThan(90);       // true     180 >  90
$alfa->gt("90° 0' 0\"");        // true     180 >  90
$alfa->isGreaterThan($gamma);   // false    180 > 360
$alfa->gt($gamma);              // false    180 > 360

$alfa = Angle::createFromDecimal(180);
$beta = Angle::createFromDecimal(90);
$gamma = Angle::createFromDecimal(90);
$alfa->isGreaterThanOrEqual(90);        // true 180 ≧  90
$alfa->gte("180 0' 0\"");               // true 180 ≧ 180
$beta->isGreaterThanOrEqual($gamma);    // true  90 ≧  90
$beta->gte(90);                         // true  90 ≧  90

$alfa = Angle::createFromDecimal(90);
$beta = Angle::createFromDecimal(180);
$alfa->isLessThan(180);     // true  90 < 180
$alfa->lt(180);             // true  90 < 180
$alfa->isLessThan($beta);   // true  90 < 180
$beta->lt($alfa);           // false 180 < 90

$alfa = Angle::createFromDecimal(90);
$beta = Angle::createFromDecimal(180);
$alfa->isLessThanOrEqual(180);      // true 90 ≦ 180
$alfa->lte(90);                     // true 90 ≦ 90
$alfa->isLessThanOrEqual($beta);    // false 90 ≦ 180
$alfa->lte($beta);                  // false 90 ≦ 180

$alfa = Angle::createFromDecimal(180);
$beta = Angle::createFromDecimal(180);
$gamma = Angle::createFromDecimal(-180);
$alfa->isEqual($beta);  // true 180 ≅ 180
$alfa->eq($gamma);      // true 180 ≅ -180

$alfa = Angle::createFromDecimal(90);
$beta = Angle::createFromDecimal(180);
$alfa->isDifferent(180);            // true   90 ≇ 180
$alfa->not(180);                    // true   90 ≇ 180
$alfa->isDifferent(-90);            // false  90 ≇ -90
$beta->not($alfa);                  // true   180 ≇ 90

You can sum two angles

$alfa = Angle::createFromDecimal(180);
$beta = Angle::createFromDecimal(270);
$gamma = Angle::sum($alfa, $beta); // 180° + 270°
(string) $gamma; // 90° 0' 0"

Note that if the sum is less than $-360^\circ$ or more than $+360^\circ$, the resulting angle will be corrected to remain between these limits.

$alfa = Angle::createFromDecimal(180);
$beta = Angle::createFromDecimal(-270);
$gamma = Angle::absSum($alfa, $beta); // 180° + (-270°)
(string) $gamma; // 270° 0' 0"

Note that if the sum is less than $0^\circ$ or more than $+360^\circ$, the resulting angle will be corrected to remain between these limits.

You can read the code documentation in ./docs/html/index.html.