marcoconsiglio/goniometry

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

v1.4.0 2025-11-11 15:50 UTC

Requires

• php: ^8.2

Requires (Dev)

• fakerphp/faker: ~1.16
• phpdocumentor/shim: ^3.8
• phpunit/phpunit: ^11

Replaces

• marcoconsiglio/trigonometry: *

MIT

• Marco Consiglio

• seconds
• Degrees
• angle
• Minutes
• radian
• angle object
• goniometry
• goniometric algebra
• angular value
• decimal angle
• radian angle

README

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

Index

• Index
• 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 > \beta$ (greater than)
    • $\alpha \ge \beta$ (greater than or equal)
    • $\alpha < \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

Installation

composer require marcoconsiglio/goniometry

Quick Start

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°

Usage

Creating an angle

Degrees, minutes and seconds

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}''$.

String

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}''$.

Decimal (float)

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}$.

Radian (float)

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$.

Getting angle values

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)

Casting

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

To decimal (float)

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.

To radian (float)

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.

To string

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.

Direction

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:

$alfa->toggleDirection();

You can check if an angle is clockwise or counterclockwise.

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

Comparison

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$.

$\alpha &gt; \beta$ (greater than)

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

$\alpha \ge \beta$ (greater than or equal)

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

$\alpha &lt; \beta$ (less than)

$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);           // true 180 < 90

$\alpha \le \beta$ (less than or equal)

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

$\alpha \cong \beta$ (equal)

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

$\alpha \ncong \beta$ (different)

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

Algebraic sum between two angles

The Sum class extends the Angle class, so you immediately obtain the algebraic sum between two angles, passing in its constructor a FromAngles builder, which is a SumBuilder.

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

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

API documentation

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