PHPackages                             xobble/grid - 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. xobble/grid

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

xobble/grid
===========

A small library to assist with converting between British National Grid (OSNG - Ordnance Survey National Grid), Irish Grid and Channel Islands Grid references and their cartesian (datum, easting, northing, accuracy) representations

1.10(2mo ago)112MITPHPPHP >=8.2CI failing

Since Oct 8Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/Xobble/Grid)[ Packagist](https://packagist.org/packages/xobble/grid)[ RSS](/packages/xobble-grid/feed)WikiDiscussions master Synced 6d ago

READMEChangelog (6)Dependencies (5)Versions (7)Used By (0)

Grid
====

[](#grid)

A small library to assist with converting between British National Grid, Irish Grid and Channel Islands Grid references and their cartesian representations

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

[](#installation)

```
$ composer require xobble/grid
```

Usage
-----

[](#usage)

```
use Xobble\Grid\Cartesian;
use Xobble\Grid\Converter;
use Xobble\Grid\GridRef\ChannelIslandsGridRef;
use Xobble\Grid\GridRef\IrishGridRef;
use Xobble\Grid\GridRef\BritishGridRef;

// 1. Instantiate the converter with the grid types you want to support

$converter = new Converter([
    new IrishGridRef(),
    new BritishGridRef(),
    new ChannelIslandsGridRef(),
]);

// 2. Start converting

// British National Grid:
$cart1 = $converter->toCartesian('SX466827');        // EPSG:27700(246600, 82700) [100m]
$converter->toGridRef($cart1);                       // SX466827

$cart2 = new Cartesian(27700, 651409, 313177, 1);
$grid2 = $converter->toGridRef($cart2);              // TG5140913177
$converter->toCartesian($grid2);                     // EPSG:27700(651409, 313177) [1m]

// Irish Grid:
$converter->toCartesian('X622997');                  // EPSG:29902(262200, 99700) [100m]

// Channel Islands Grid:
$converter->toCartesian('WV305754');                 // EPSG:32630(530500, 5475400) [100m]

// An UnsupportedRefException will be triggered for unsupported grid references or cartesian coordinates:
$converter->toCartesian('AB22997');                  // UnsupportedRefException

// A GridRefException will be triggered if trying to convert badly constructed Cartesians:
//
// GridRefException: Accuracy + easting / northing mismatch
// (States 100m accuracy, but easting/northing have meter and tens accuracy digits):
$badCart1 = new Cartesian(27700, 651409, 313122, 100);
$converter->toGridRef($badCart1);

// GridRefException: Accuracy must be a power of 10 with an integer exponent (e.g. 1, 10, 100, 1000...)
$badCart2 = new Cartesian(27700, 651400, 313100, 200);
$converter->toGridRef($badCart2) ;
```

Supported Datums / Grids
------------------------

[](#supported-datums--grids)

- EPSG:27700 - class BritishGridRef - [British National Grid](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid)
- EPSG:29902 - class IrishGridRef - [Irish Grid](https://en.wikipedia.org/wiki/Irish_grid_reference_system)
- EPSG:32630 - class ChannelIslandsGridRef - [Channel Islands Grid](https://www.bwars.com/content/channel-islands-how-give-location-reference)

GridRef interface
-----------------

[](#gridref-interface)

Other grid reference systems can be supporting by creating classes that implement the following interface.

```
use Xobble\Grid\Cartesian;

interface GridRef
{
    public function getDatum() : int;
    public function getGridReferenceName() : string;

    public function toCartesian(string $gridRef) : Cartesian;
    public function toGridRef(Cartesian $cartesian) : string;
}
```

```
use Xobble\Grid\Cartesian;
use Xobble\Grid\GridRef\BritishGridRef;

$grid = new BritishGridRef();

$grid->getGridReferenceName();                   // British National Grid
$grid->getDatum();                               // 27700
$grid->toCartesian('SR123456');                  // Returns a Cartesian - "EPSG:27700(112300, 145600) [100m]"
$grid->toCartesian('HL123456');                  // throws UnsupportedRefException

$cart1 = new Cartesian(27700, 651409, 313177, 1);
$cart2 = new Cartesian(29902, 651409, 313177, 1);

$ref1 = $grid->toGridRef($cart1);                // Returns a string - "TG5140913177"
$grid->toGridRef($cart2);                        // throws UnsupportedRefException

$grid->toCartesian($ref1);                       // EPSG:27700(651409, 313177) [1m]
```

The BritishGridRef and IrishGridRef constructs optionally take an array of options which can be used to configure which grid reference prefixes are recognised as valid. The 'allowed\_references' option can be set either to null to allow any prefix, or to an array of valid prefix strings.

```
use Xobble\Grid\GridRef\IrishGridRef;

$gridLimited = new IrishGridRef([
    'allowed_references' => [
        'A', 'B', 'C', 'D', 'F', 'G', 'H', 'J', 'L', 'M',
        'N', 'O', 'Q', 'R', 'S', 'T', 'V', 'W', 'X', 'Y',
    ]
]);
```

In addition to this, the BritishGridRef by default also disallows the prefixes WA and WV as these are used to denote Channel Islands grid references. This can however be turned off with an option:

```
use Xobble\Grid\GridRef\BritishGridRef;

$gridNoCI = new BritishGridRef([
    'grid_exclude_channel_islands' => false,
    'allowed_references' => null                     // Allow any prefix
]);
```

Cartesian class
---------------

[](#cartesian-class)

```
use Xobble\Grid\Cartesian;

$cart = new Cartesian(27700, 651409, 313177, 1);

echo $cart->getDatum();    // 27700
echo $cart->getEasting();  // 651409
echo $cart->getNorthing(); // 313177
echo $cart->getAccuracy(); // 1
echo $cart;                // EPSG:27700(651409, 313177) [1m]
```

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance88

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity75

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 ~470 days

Recently: every ~588 days

Total

6

Last Release

62d ago

PHP version history (2 changes)1.0PHP >=7.1

1.10PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/386d480c514d44bf0e91832e8c38dec1f65dcbb1e1adc007a15d09099a89c1b7?d=identicon)[WubbleWobble](/maintainers/WubbleWobble)

---

Top Contributors

[![WubbleWobble](https://avatars.githubusercontent.com/u/1557721?v=4)](https://github.com/WubbleWobble "WubbleWobble (26 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/xobble-grid/health.svg)

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

###  Alternatives

[phpcr/phpcr-migrations

Migrations for PHPCR

421.4M2](/packages/phpcr-phpcr-migrations)[wablas/wablas-client-php

(Unoficial) Wablas Client PHP

141.4k](/packages/wablas-wablas-client-php)

PHPackages © 2026

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