mfmbarber/hackpostcodes

A hack library for using postcodes.io

HackPostcodes

HackPostcodes is a library written in Hack that wraps around the https://postcodes.io API., _(*1)

Motivation

I've been learning the Hack programming language, and the Hip Hop Virtual Machine (HHVM) - so seemed like a good excuse to make something usable., _(*2)

Dependancies

• This was written using HHVM v3.18, it's probably backwards compatible to a degree though
• PHPUnit 5.7.* - There isn't compatibility with HHVM above this yet

Installation

You can install this library using composer:, _(*3)

$ composer install mfmbarber/HackPostcodes

Usage

To use the Postcodes library you first need to ensure you instantiate the CurlRequest class, and inject this into Postcodes as a constructor dependancy. This allows you to swap out the CurlRequest class with your own implementation if required. It also allows us to mock our dependancy when testing., _(*4)

Once you have instantiated the Postcodes class you can then call any of the following methods off of this:, _(*5)

• lookup(string $postcode) : Map Use this to lookup a single postcode and get back a map of the result, _(*6)

• lookupBulk(Vector $postcodes) : Vector, _(*7)

• lookupLatLon(Pair<float, float> $geolocation) : Vector Use this to look up at latitude / longitude point and return a vector of maps - where each map represents a local postcodes to that position, _(*8)

• lookupBulkLatLong(Vector<Pair<float, float>> $geolocations) : VectorVector Use this to lookup a vector of longitude / latitude points and return a vector, of vectors, of maps. Where each first level represents a corresponding longitude / latitude point, and each sub-vector represents the local postcodes to that location, _(*9)

• isValid(string $postcode) : bool Check to see if a postcode is valid (both regex and a UK postcode), _(*10)

• getNearest(string $postcode) : Vector, _(*11)

• autocomplete(string $postcode, int $limit = 10) : Vector Given part of a postcode, and the amount of results to return (limit is 100), return a Vector of potential full postcode strings, _(*12)

• random() : Map Return a random postcode as a map, _(*13)

-getDistance(string $postcode1, string $postcode2) : num Return the shortest distance (straight line) between two postcodes, this uses the Haversine formula to calculate., _(*14)

<?hh

include 'vendor/autoload.php';
use mfmbarber\HackPostcodes\Postcodes;
use mfmbarber\HackPostcodes\CurlRequest;

$postcodes = new Postcodes(new CurlRequest());

$x = $postcodes->lookup('DT51HG');
var_dump($x);

$y = $postcodes->lookupBulk(Vector {'DT51HG', 'BH122BL'});
var_dump($y);

$z = $postcodes->getDistance('DT51HG', 'BH122BL');
var_dump($z);

Tests

Tests have been written using PHPUnit, and can be run from the root of the project:, _(*15)

$ hhvm vendor/bin/phpunit tests/

Contributing

To contribute to this project, _(*16)

• Create a fork of the project
• Create a feature/bugfix branch off of develop
• Commit your changes
• Write your tests
• Once you are happy - PR back into develop
• Once reviewed, the PR is accepted.
• Hurrah!

Ensure you comment your code!, _(*17)

License

This project is fully open sourced under MIT license, _(*18)