PHPackages                             stui/bestagons - 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. stui/bestagons

ActiveLibrary[Utility & Helpers](/categories/utility)

stui/bestagons
==============

PHP Library for creating hexagonal maps

1.0.0(1mo ago)00GPL-3.0-or-laterPHP

Since May 7Pushed 1mo agoCompare

[ Source](https://github.com/stuii/bestagons)[ Packagist](https://packagist.org/packages/stui/bestagons)[ RSS](/packages/stui-bestagons/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

[![bestagons](assets/bestagons-logo.png)](assets/bestagons-logo.png)

Bestagons is a PHP library for creating and managing hexagonal maps using axial and cube coordinates. It is based on the excellent hex grid logic and algorithms from [Red Blob Games](https://www.redblobgames.com/grids/hexagons/).

Installation
------------

[](#installation)

You can install the package via Composer:

```
composer require stui/bestagons
```

Usage
-----

[](#usage)

### The Hex Class

[](#the-hex-class)

The `Hex` class represents a hexagon in a grid. It can be represented using axial coordinates ($q$, $r$) or cube coordinates ($q$, $r$, $s$). Bestagon can handle both and in fact will always store cube coordinates internally.

```
use Stui\Bestagons\Hex\Hex;

$hex = new Hex(1, 2);
echo $hex->q; // 1
echo $hex->r; // 2
echo $hex->s; // -3 (calculated automatically)
```

#### Equality

[](#equality)

```
$hex = new Hex(1, 0);
$hex->equal(new Hex(0, 1)); // false

$hex = new Hex(1, 0);
$hex->equal(new Hex(1, 0)); // true
```

#### Coordinate arithmetic

[](#coordinate-arithmetic)

```
$hex1 = new Hex(1, 0);
$hex2 = new Hex(0, 1);

$sum = $hex1->add($hex2);
$diff = $hex1->subtract($hex2);
$scaled = $hex1->multiply(2);
```

#### Distance and Neighbors

[](#distance-and-neighbors)

For help with directions, please see [here](https://www.redblobgames.com/grids/hexagons/#neighbors).

For a quick reference, the directions - expressed in cardinal directions - are:

Pointy TopFlat Top0EastSouth-East1North-EastNorth-East2North-WestNorth3WestNorth-West4South-WestSouth-West5South-EastSouth```
$hex1 = new Hex(0, 0);
$hex2 = new Hex(2, 0);

$distance = $hex1->distanceTo($hex2); // 2

// Get a neighbor (0-5)
$neighbor = $hex1->neighbor(0);

// Get a diagonal neighbor (0-5)
$diagonal = $hex1->diagonalNeighbor(0);
```

### Fractional Hex and Rounding

[](#fractional-hex-and-rounding)

Useful for operations like linear interpolation between two hexagons.

```
$hex1 = new Hex(0, 0);
$hex2 = new Hex(10, -10);

$fractionalHex = $hex1->lerpHex($hex2, 0.57); // Returns a FractionalHex instance with interpolated coordinates
$roundedHex = $fractionalHex->round(); // Returns a Hex instance
```

### Maps

[](#maps)

The `Map` class allows you to store and retrieve hexagons.

```
use Stui\Bestagons\Map\Map;
use Stui\Bestagons\Hex\Hex;

$map = new Map();
$hex = new Hex(1, 1);

$map->store($hex);

if ($map->has(1, 1)) {
    $retrievedHex = $map->get(1, 1);
}

$neighbors = $map->getNeighborsOf($hex);
```

#### Rectangular Maps

[](#rectangular-maps)

A shape of map that generates a rectangular grid of hexagons.

The params define how far out the rectangle generates from the base point.

[![Examples of rectangular maps](assets/rectangular-maps.png)](assets/rectangular-maps.png)

```
use Stui\Bestagons\Map\Shapes\RectangularMap;
use Stui\Bestagons\Enums\HexOrientation;

$map = new RectangularMap(
    left: 0,
    right: 5,
    top: 0,
    bottom: 5,
    orientation: HexOrientation::POINTY_TOP
);
```

Credits
-------

[](#credits)

All logic and algorithms in this library are based on the work of Amit Patel at [Red Blob Games](https://www.redblobgames.com/grids/hexagons/).

If you want to understand the math behind hex grids, that is the place to go.

License
-------

[](#license)

The GPL-3.0-or-later. Please see [License File](LICENSE) for more information.

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance93

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/de7344041bf2746326cd07fb71ec1987fe73bc4925e80945eb5e95e4101baf9a?d=identicon)[stui](/maintainers/stui)

---

Top Contributors

[![stuii](https://avatars.githubusercontent.com/u/14111414?v=4)](https://github.com/stuii "stuii (7 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/stui-bestagons/health.svg)

```
[![Health](https://phpackages.com/badges/stui-bestagons/health.svg)](https://phpackages.com/packages/stui-bestagons)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)