PHPackages marcoconsiglio/goniometry - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. marcoconsiglio/goniometry ActiveLibrary[Utility & Helpers](/categories/utility) marcoconsiglio/goniometry ========================= A PHP support for string, decimal, radian and object angles, providing goniometric algebra and comparison between angles. v6.1.2(4w ago)0472↓80%[1 issues](https://github.com/MarcoConsiglio/goniometry/issues)1MITPHPPHP ^8.4 Since Oct 8Pushed 4w agoCompare [ Source](https://github.com/MarcoConsiglio/goniometry)[ Packagist](https://packagist.org/packages/marcoconsiglio/goniometry)[ RSS](/packages/marcoconsiglio-goniometry/feed)WikiDiscussions main Synced 3w ago READMEChangelog (10)Dependencies (12)Versions (26)Used By (1) [goniometry](https://github.com/MarcoConsiglio/goniometry?tab=readme-ov-file#goniometry) ======================================================================================== [](#goniometry) [![GitHub License](https://camo.githubusercontent.com/cbe4c05c783bb20fa835d51b841512ecc29ae27c09f49542651c3cfa8b09204a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6172636f636f6e7369676c696f2f676f6e696f6d65747279)](https://camo.githubusercontent.com/cbe4c05c783bb20fa835d51b841512ecc29ae27c09f49542651c3cfa8b09204a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d6172636f636f6e7369676c696f2f676f6e696f6d65747279)[![GitHub Release](https://camo.githubusercontent.com/52dccf0e1684c272f75b3f80f3340e8e97acbf0dc1d9fddd7b6c9da7f66f2c6c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d6172636f636f6e7369676c696f2f676f6e696f6d65747279)](https://camo.githubusercontent.com/52dccf0e1684c272f75b3f80f3340e8e97acbf0dc1d9fddd7b6c9da7f66f2c6c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6d6172636f636f6e7369676c696f2f676f6e696f6d65747279)[![Static Badge](https://camo.githubusercontent.com/83b16695c53c3e2a9be29426524d7178da45db55c35fe6d3d9d094765f23fbcf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76362e312e322d7768697465)](https://camo.githubusercontent.com/83b16695c53c3e2a9be29426524d7178da45db55c35fe6d3d9d094765f23fbcf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d76362e312e322d7768697465) [![Static Badge](https://camo.githubusercontent.com/c9a65581bace5afa22c879002c672ea7a12840d729b7e01c317d7d51810a08b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c696e65253230636f7665726167652d3130302532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929)](https://camo.githubusercontent.com/c9a65581bace5afa22c879002c672ea7a12840d729b7e01c317d7d51810a08b7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c696e65253230636f7665726167652d3130302532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929)[![Static Badge](https://camo.githubusercontent.com/81914ffe9dca1ead33eeafec916529adf289ac232fac2ee68f815b9f98664550/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4272616e6368253230636f7665726167652d3130302532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929)](https://camo.githubusercontent.com/81914ffe9dca1ead33eeafec916529adf289ac232fac2ee68f815b9f98664550/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4272616e6368253230636f7665726167652d3130302532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929)[![Static Badge](https://camo.githubusercontent.com/b0042e2f4cb42814e4f5feaef8d00b1273bfddeece2e271060ace823066d05f7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50617468253230636f7665726167652d39392532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929)](https://camo.githubusercontent.com/b0042e2f4cb42814e4f5feaef8d00b1273bfddeece2e271060ace823066d05f7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50617468253230636f7665726167652d39392532352d7267622834302532433136372532433639293f6c6162656c436f6c6f723d25323366666626636f6c6f723d726762283430253243313637253243363929) A PHP support for string, decimal, radian and object angles, providing goniometric algebra and comparison between angles. Index ===== [](#index) - [Requirements](#requirements) - [Installation](#installation) - [Quick Start](#quick-start) - [Usage](#usage) - [Creating an angle](#creating-an-angle) - [Sexagesimal (degrees, minutes, seconds)](#sexagesimal_values) - [Sexagesimal string](#sexadecimal_value) - [Sexadecimal float](#sexadecimal_value) - [Radian float](#radian_value) - [Getting angle values](#getting-angle-values) - [Casting](#casting) - [To sexadecimal (float)](#toFloat) - [To sexadecimal (object)](#toSexadecimalDegrees) - [To radian (float)](#toRadian) - [To string](#to-string) - [Rotation direction](#rotation-direction) - [Opposite direction](#opposite-direction) - [Comparison](#comparison) - [$\\alpha \\gt \\beta$ (greater than)](#greater-than) - [$\\alpha \\ge \\beta$ (greater than or equal)](#greater-than-or-equal) - [$\\alpha \\lt \\beta$ (less than)](#less-than) - [$\\alpha \\le \\beta$ (less than or equal)](#less-than-or-equal) - [$\\alpha \\cong \\beta$ (equal)](#equal) - [$\\alpha \\ncong \\beta$ (different)](#different) - [Fuzzy Comparison](#fuzzy-comparison) - [$\\alpha \\approxeq \\beta$ (almost equal)](#almost-equal) - [Algebraic sum between two angles](#algebraic-sum-between-two-angles) - [FakerPHP support](#fakerphp-support) - [API documentation](#api-documentation) Requirements ============ [](#requirements) - PHP v8.4+ - [BC Math](https://www.php.net/manual/en/book.bc.php) PHP extension Installation ============ [](#installation) `composer require marcoconsiglio/goniometry` Quick Start =========== [](#quick-start) Import this class to represent angles. ``` use MarcoConsiglio\Goniometry\Angle; ``` Create an `Angle` object (-360°/+360°). ``` $alfa = Angle::createFromValues(180, 30); $beta = Angle::createFromString("180° 30'"); $gamma = Angle::createFromDecimal(180.5); $delta = Angle::createFromRadian(M_PI); // 180° ``` Create an `AngularDistance` object (-180°/+180°). ``` $alfa = AngularDistance::createFromValues(180, 30); $beta = AngularDistance::createFromString("180° 30'"); $gamma = AngularDistance::createFromDecimal(180.5); $delta = AngularDistance::createFromRadian(M_PI); // 180° ``` Both `Angle` and `AngularDistance` implements the `Angle` interface. Usage ===== [](#usage) Creating an angle ----------------- [](#creating-an-angle) ### Sexagesimal (`int` degrees, `int` minutes, `float` seconds) [](#sexagesimal-int-degrees-int-minutes-float-seconds-) This creates an angle from its values in degrees, minutes and seconds: ``` $alfa = Angle::createFromValues(180, 12, 43.4618, Rotation::CLOCKWISE); // -180° 12' 43.4618" ``` `Rotation::COUNTER_CLOCKWISE` is the plus sign, `Rotation::CLOCKWISE` is the minus sign. A null angle (exactly $0^\\circ\\space0'\\space0"$) will always have a `Rotation::COUNTER_CLOCKWISE`. ### Sexagesimal (`string`) [](#sexagesimal-string) This creates an angle from its textual representation: ``` $beta = Angle::createFromString("-180° 12' 43.4618\""); ``` 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}''$. ### Sexadecimal value (`float`) [](#sexadecimal-value-float) This create an angle from its decimal representation: ``` $gamma = Angle::createFromDecimal(180.2119); // 180.2119° $gamma = Angle::createFromDecimal(-180.2119); // -180.2119° $gamma = Angle::createFromDecimal(301.0); // 1.0° ``` ### Radian (`float`) [](#radian-float-) This create an angle from its radian representation: ``` $delta = Angle::createFromRadian(M_PI); // π ≅ 180° $delta = Angle::createFromRadian( new Radian(Number::π()) ); // π = 180° $delta = Angle::createFromRadian(-M_PI); // -π ≅ -180° $delta = Angle::createFromRadian(2 * M_PI); // 2π ≅ 0° ``` If you need a precise π value, you can pass a `Radian` object constructed with the `Number::π()` static method that return the π constant with an arbitrary precision up to 54 digits. The `Radian` class extend the `ModularNumber` class, whose API is documented in [marcoconsiglio/modular-arithmetic](https://github.com/MarcoConsiglio/php-modular-arithmetic). For more info on `Number::π()` check the API of [marcoconsiglio/bcmath-extended](https://github.com/MarcoConsiglio/bcmath-extended). Getting angle values -------------------- [](#getting-angle-values) You can obtain sexagesimal values separated in an array (simple by default, or associative): ``` $values = $alfa->getDegrees(); echo $values[0]; // int echo $values[1]; // int echo $values[2]; // float $values = $alfa->getDegrees(true); echo $value['degrees']; // int echo $value['minutes']; // int echo $value['seconds']; // float ``` The angle's direction determines the sign of the degrees value. There are read-only properties too: ``` /** @var Degrees */ (string) $alfa->degrees; // 180° /** @var Minutes */ (string) $alfa->minutes; // 12' /** @var Seconds */ (string) $alfa->seconds; // 43" /** @var Rotation */ $alfa->direction; // Rotation::CLOCKWISE (-1) ``` The `Degrees`, `Minutes`, and `Seconds` extends `ModularNumber`, whose API is documented in [marcoconsiglio/modular-arithmetic](https://github.com/MarcoConsiglio/php-modular-arithmetic). You can cast `Degrees`, `Minutes`, and `Seconds` to `string`. ### Rotation direction [](#rotation-direction) Positive angles are represented by the enum constant ``` Rotation::COUNTER_CLOCKWISE; // 1 ``` while negative angles are represented by the opposite enum constant: ``` Rotation::CLOCKWISE; // -1 ``` You can toggle the rotation direction: ``` $beta = $alfa->oppositeRotation(); ``` Since the `Angle` instance is immutable, the `toggleRotation()` 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 // If $beta is a negative angle $beta->isCounterClockwise(); // false $beta->isClockwise(); // true ``` ### Opposite direction [](#opposite-direction) You can calc the opposite direction of an object implementing the `Angle` interface with the method `oppositeDirection()`. ``` $alfa = Angle::createFromDecimal(90.0); $beta = $alfa->oppositeDirection(); (string) $beta; // 180° 0' 0" ``` Casting ------- [](#casting) ### To `float` sexadecimal degrees [](#to-float-sexadecimal-degrees-) You can cast the angle to `float` type, with optional precision up to `PHP_FLOAT_DIG` decimal places: ``` $alfa->toFloat(); // 180.211971543295645 $alfa->toFloat(4); // 180.2119 $alfa->toFloat(200) // 180.211971543295645 ``` You can specify a precision up to `PHP_FLOAT_DIG` decimal places. If the number of decimal places is not set, `PHP_FLOAT_DIG` is used. ### To `SexadecimalDegrees` type [](#to-sexadecimaldegrees-type-) If you need an arbitrary precision, you can obtain a `SexadecimalDegrees` instance representing the sexadecimal value of the angle. ``` $sexadecimal = $alfa->toSexadecimalDegrees(); /** @var Number */ (string) $sexadecimal->value;// 180.2119715432956455962174521226543543 /** @var float */ $sexadecimal->value(); // 180.211971543295645 /** @var float */ $sexadecimal->value(3); // 180.212 /** @var float */ $sexadecimal->value(12); // 180.211971543296 ``` The `$value` property is a `Number` object extending the `BCMath\Number` class, whose API is documented in [marcoconsiglio/bcmath-extended](https://github.com/MarcoConsiglio/bcmath-extended). The `value()` method cast the `SexadecimalDegrees` object to `float`. You can specify a precision up to `PHP_FLOAT_DIG` decimal places. If the number of decimal places is not set, `PHP_FLOAT_DIG` is used. ### To `float` radian [](#to-float-radian-) You can cast the angle to radian (`float`), with optional precision up to `PHP_FLOAT_DIG` decimal places: ``` $alfa->toRadian(); // 3.141592653589793 $alfa->toRadian(3); // 3.141 $alfa->toRadian(200); // 3.141592653589793 ``` You can specify a precision up to `PHP_FLOAT_DIG` decimal places. If the number of decimal places is not set, `PHP_FLOAT_DIG` is used. ### To `string` sexagesimal [](#to-string-sexagesimal-) You can cast the angle to a string representation: ``` (string) $alfa; // 180° 30' 25.757385" ``` **WARNING!** In this case, maximum precision is *unknown*. The `Seconds` class uses the [BCMath extension](https://www.php.net/manual/en/book.bc.php) behind the scenes. The seconds value is stored with arbitrary precision, so in some cases the number of seconds could potentially have many digits, making the string very long. Comparison ---------- [](#comparison) You can compare an `Angle` or `AngularDistance` object against a *sexadecimal* or *sexagesimal* value. 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 a sexadecimal `float`](#toFloat) and then perform the arithmetic comparison, meaning that $-90.0^\\circ\\lt+90.0^\\circ$. Each comparison can be performed against - a `string` angle (sexagesimal), - an `int` (sexagesimal degrees), - a `float` (sexadecimal degrees), - or another instance implementing the `Angle` interface. *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 against a `float` (sexadecimal). ``` $alfa = Angle::createFromDecimal(89.999); $alfa->isEqualTo(90.0, 0); // true with precision 0 $alfa->isEqualTo(90.0, 3); // false with precision 3 ``` ### $\\alpha &gt; \\beta$ (greater than) [](#alpha--beta-greater-than-) ``` $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 ``` ### $\\alpha ≧ \\beta$ (greater than or equal) [](#alpha--beta-greater-than-or-equal-) ``` $alfa = Angle::createFromDecimal(180); $beta = Angle::createFromDecimal(90); $gamma = Angle::createFromDecimal(90); $alfa->isGreaterThanOrEqualTo(90); // true 180 ≧ 90 $alfa->gte("180 0' 0\""); // true 180 ≧ 180 $beta->isGreaterThanOrEqualTo($alfa); // true 90 ≧ 180 $beta->gte(90); // true 90 ≧ 90 ``` ### $\\alpha &lt; \\beta$ (less than) [](#alpha--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); // false 180 < 90 ``` ### $\\alpha ≦ \\beta$ (less than or equal) [](#alpha--beta-less-than-or-equal-) ``` $alfa = Angle::createFromDecimal(90); $beta = Angle::createFromDecimal(180); $alfa->isLessThanOrEqualTo(180); // true 90 ≦ 180 $alfa->lte(90); // true 90 ≦ 90 $alfa->isLessThanOrEqualTo($beta); // false 90 ≦ 180 $alfa->lte($beta); // false 90 ≦ 180 ``` ### $\\alpha \\cong \\beta$ (equal) [](#alpha-cong-beta-equal-) ``` $alfa = Angle::createFromDecimal(180); $beta = Angle::createFromDecimal(180); $gamma = Angle::createFromDecimal(-180); $alfa->isEqualTo($beta); // true 180 ≅ 180 $alfa->eq($gamma); // true 180 ≅ -180 ``` ### $\\alpha \\ncong \\beta$ (different) [](#alpha-ncong-beta-different-) ``` $alfa = Angle::createFromDecimal(90); $beta = Angle::createFromDecimal(180); $alfa->isDifferentThan(180); // true 90 ≇ 180 $alfa->not(180); // true 90 ≇ 180 $alfa->isDifferentThan(-90); // false 90 ≇ -90 $beta->not($alfa); // true 180 ≇ 90 ``` Fuzzy Comparison ---------------- [](#fuzzy-comparison) When comparing two `Angle`s sometimes their difference is negligible. In this case you can use a fuzzy comparison specifing a delta error `Angle` within which the comparison will be succesful. *Delta* (Δ) is the double of *epsilon* error (±ε). ### $\\alpha \\approxeq \\beta$ (almost equal) [](#alpha-approxeq-beta-almost-equal) ``` $alfa = Angle::createFromDecimal(90.345); $beta = Angle::createFromValue(90); $delta = Angle::createFromValue(4); // ±2° error $alfa->fuzzyEqual($beta, $delta); // true $alfa->feq($beta, $delta); // true ``` Algebraic sum between two angles -------------------------------- [](#algebraic-sum-between-two-angles) You can sum two angles. An angle of type `AngularDistance` do not have the `absSum()` methods. ### Relative sum [](#relative-sum) The relative sum can return both positive or negative angle. ``` $alfa = Angle::createFromDecimal(180); $beta = Angle::createFromDecimal(-270); $gamma = $alfa // 180° + ->sum($beta); // -270° = (string) $gamma; // -90° ``` ### Absolute sum [](#absolute-sum) The absolute sum will always return a positive angle. ``` $alfa = Angle::createFromDecimal(180); $beta = Angle::createFromDecimal(-270); $gamma = $alfa // 180° + ->absSum($beta); //-270° = (string) $gamma; // 270° ``` ``` $alfa = Angle::createFromDecimal(-180); $beta = Angle::createFromDecimal(-270); $gamma = $alfa // -180° + ->absSum($beta); // -270° (string) $gamma; // 270° ``` FakerPHP support ==================================================== [](#fakerphp-support-) This library provides support to [FakerPHP](https://fakerphp.org/) through the `WithAngleFaker` trait. Here's a list of the available methods. MethodReturn typeMin (included)Min (excluded)Max (included)Max (excluded)`randomPrecision()``int`0`PHP_FLOAT_DIG``randomDegrees()``Degrees`0°359°`randomMinutes()``Minutes`0'59'`randomSeconds()``Seconds`0"60"`randomAngle()``Angle`-360°+360°`positiveRandomAngle()``Angle`0°+360°`negativeRandomAngle()``Angle`-360°0°`randomDirection()``Direction``CLOCKWISE``COUNTER_CLOCKWISE``randomSexagesimalString()``string`-360°+360°`randomSexagesimal()``SexagesimalDegrees`-360°+360°`positiveRandomSexagesimal()``SexagesimalDegrees`0°+360°`negativeRandomSexagesimal()``SexagesimalDegrees`-360°0°`randomSexadecimal()``float`-360°+360°`positiveRandomSexadecimal()``float`0°+360°`negativeRandomSexadecimal()``float`-360°0°`randomRadian()``Radian`-2π+2π`positiveRandomRadian()``Radian`0+2π`negativeRandomRadian()``Radian`-2π0`positiveRandomAngularDistance()``AngularDistance`0°+180°`negativeRandomAngularDistance()``AngularDistance`-180°0°Check the [API documentation](#api-documentation) to find out more info about these methods. API documentation ================= [](#api-documentation) You can read the code documentation in `./docs/html/index.html`. ### Health Score 48 — FairBetter than 94% of packages Maintenance94 Actively maintained with recent releases Popularity16 Limited adoption so far Community8 Small or concentrated contributor base Maturity63 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Recently: every ~4 days Total 24 Last Release 29d ago Major Versions v1.5.1 → v2.0.02025-12-17 v2.0.1 → v3.0.02026-03-17 v3.1.0 → v4.0.02026-04-08 v4.2.0 → v5.0.02026-05-07 v5.0.0 → v6.0.02026-05-11 PHP version history (2 changes)v1.0.0PHP ^8.2 v1.5.0PHP ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/5fb36102dfc597a74e864afc65952e328f158bff88f21ad993c1d79c51c80133?d=identicon)[MarcoConsiglio](/maintainers/MarcoConsiglio) --- Top Contributors [![MarcoConsiglio](https://avatars.githubusercontent.com/u/39809954?v=4)](https://github.com/MarcoConsiglio "MarcoConsiglio (82 commits)") --- Tags algebraic-geometryangleangle-measurementanglesdegrees-minutes-secondsgoniometricgoniometrogoniometryradiansradiantsexadecimal-degreessexagesimal-degreessecondsMinutesDegreesangleradianangle objectgoniometrygoniometric algebraangular valuedecimal angleradian angle ### Code Quality TestsPHPUnit Static AnalysisRector ### Embed Badge ![Health badge](/badges/marcoconsiglio-goniometry/health.svg) ``` [![Health](https://phpackages.com/badges/marcoconsiglio-goniometry/health.svg)](https://phpackages.com/packages/marcoconsiglio-goniometry) ``` ### Alternatives [data-values/geo Geographical value objects, parsers and formatters 17646.1k21](/packages/data-values-geo)[verbb/formie The most user-friendly forms plugin for Craft. 100387.6k57](/packages/verbb-formie)[solspace/craft-freeform The most flexible and user-friendly form building plugin! 53675.5k15](/packages/solspace-craft-freeform)[mtownsend/read-time A PHP package to show users how long it takes to read content. 282616.7k2](/packages/mtownsend-read-time)[khill/php-duration Converts between colon formatted time, human-readable time and seconds 1571.8M20](/packages/khill-php-duration)[blackfire/player A powerful web crawler and web scraper with Blackfire support 49517.1k](/packages/blackfire-player) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)