PHPackages                             becklyn/postal-code-proximity - 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. becklyn/postal-code-proximity

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

becklyn/postal-code-proximity
=============================

Calculates near postal codes (given, that a pre-generated postal code lookup database exists).

v0.1.1(11y ago)131BSD-3-ClausePHPPHP >=5.3

Since Mar 5Pushed 11y ago2 watchersCompare

[ Source](https://github.com/Becklyn/BecklynPostalCodeProximity)[ Packagist](https://packagist.org/packages/becklyn/postal-code-proximity)[ Docs](https://github.com/Becklyn/BecklynPostalCodeProximity)[ RSS](/packages/becklyn-postal-code-proximity/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

Becklyn Postal Code Proximity
=============================

[](#becklyn-postal-code-proximity)

If you have a pre-generated database with a mapping of postal codes to latitude & longitude, this library will help you with searching for nearby postal codes (in a given radius).

Usage
-----

[](#usage)

First you need to create a query generator. The query generator is responsible for generating the SQL for loading the data from the database. You need to specify the names of the table and the columns of your postal code table.

```
use Becklyn\PostalCodeProximity\QueryGenerator;

$queryGenerator = new QueryGenerator($tableName, $latitudeColumn = "lat", $longitudeColumn = "lng", $postalCodeColumn = "zip");
```

Afterwards, you need to use a database adapter. There are already working adapters for PDO and mysqli.

```
use Becklyn\PostalCodeProximity\Adapter\PdoAdapter;

$pdo = new \PDO("...", "user", "password");
$databaseAdapter = new PdoAdapter($pdo, $queryGenerator);
```

or

```
use Becklyn\PostalCodeProximity\Adapter\MysqliAdapter;

$mysqli = new \mysqli("localhost", "user", "password", "dbname");
$databaseAdapter = new MysqliAdapter($mysqli, $queryGenerator);
```

And now you can query for nearby postal codes:

```
use Becklyn\PostalCodeProximity\PostalCodeLocator;

$postalCodeLocator = new PostalCodeLocator($databaseAdapter);
$postalCodeLocator->loadNearPostalCodes($postalCode, $radius, $limit = null);
```

- `$postalCode` is the postal code, like `"12345"`
- `$radius` is the radius in km (air-line distance)
- `$limit` (optional) limit the number of results

### Return value

[](#return-value)

You will receive an array of `NearPostalCode`

```
$nearPostalCode->getPostalCode();
$nearPostalCode->getDistanceInKm();
```

### Error cases

[](#error-cases)

There are two possible error case (except of exceptions directly from the databases):

- `AmbiguousPostalCodeException`: if a given postal code is found multiple times in the postal code database
- `QueryException`: handles all error cases originating in the database. **Warning:** the exception messages may contain sensitive information.

Recommended database structure
------------------------------

[](#recommended-database-structure)

- `postal_code CHAR(5)` (may vary depending on your country of origin)
- `latitude DOUBLE`
- `longitude DOUBLE`

You should add an unique index to the `postal_code` fields and indexes on `latitude` and `longitude`.

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 66.7% 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 ~0 days

Total

2

Last Release

4092d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1044355?v=4)[Becklyn Studios](/maintainers/becklyn)[@Becklyn](https://github.com/Becklyn)

---

Top Contributors

[![tkasper](https://avatars.githubusercontent.com/u/1580938?v=4)](https://github.com/tkasper "tkasper (2 commits)")[![apfelbox](https://avatars.githubusercontent.com/u/1032411?v=4)](https://github.com/apfelbox "apfelbox (1 commits)")

---

Tags

postal-code

### Embed Badge

![Health badge](/badges/becklyn-postal-code-proximity/health.svg)

```
[![Health](https://phpackages.com/badges/becklyn-postal-code-proximity/health.svg)](https://phpackages.com/packages/becklyn-postal-code-proximity)
```

PHPackages © 2026

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