Postcode

Gatepost\Postcode\Postcode

A Nigerian digital postcode that parse() accepted, such as EK-01-A03-FK-01. Each form holds the same code. The static methods read text that users type or paste, with no network access.

Unofficial. Not made or endorsed by NIPOST.

Members

• SPEC_VERSION = '0.3.0': The version of the Gatepost spec that this package implements.
• string $compact: The code with no separators, for example EK01A03FK01.
• string $canonical: The code with hyphens between segments, for example EK-01-A03-FK-01.
• string $display: The code with spaces between segments, for example EK 01 A03 FK 01.
• Segments $segments: Each segment on its own.
• Precision $precision: The most precise segment in the code.

Methods

parse()

public static function parse(string $input, bool $allowPartial = false): ParseResult

Reads a postcode that a user typed or pasted. It accepts spaces, hyphens, dashes and any letter case. It never throws. Input over the spec’s input limit fails with BadLength before parse normalises it, so long text cannot stall a server. Input that is not valid UTF-8 fails with BadCharacter, or with BadLength when it has more than 4 bytes for each code point of the input limit.

After normalisation, parse applies these checks in order. The first check that fails gives the error code: Empty, LegacyCode, BadCharacter, BadLength, UnknownState and BadSegment. For UnknownState and BadSegment, the error names the segment, and it can suggest the canonical form of one fixed code. The fix replaces a look-alike character in the wrong place, such as the letter O in an LGA. It never changes the district.

$result = Postcode::parse('ek 01 a03 fk 01');
if ($result->isOk()) {
    echo $result->value->canonical; // EK-01-A03-FK-01
}

Parameters

Name	Meaning
$input	Text from a user.
$allowPartial	Also accept a code that stops after the state, LGA, district or area.

normalize()

public static function normalize(string $input): string

Normalises text that a user typed or pasted. It applies Unicode NFKC to each character whose NFKC form holds only ASCII characters and separators, such as full-width letters. It removes the separators that the spec lists: white space, hyphens and dashes, the full stop and some zero-width characters. Then it makes the ASCII letters a to z upper case. It keeps every other character and every byte that is not valid UTF-8. It does not check the result, and it does not limit the length of its input.

echo Postcode::normalize(' ek-01 a03.fk-01 '); // EK01A03FK01

Parameters

Name	Meaning
$input	Text from a user.

isLegacy()

public static function isLegacy(string $input): bool

Tells whether text is an old 6-digit NIPOST postcode, which names an area, not a building. It is a thin wrapper over parse(), so it is false for input over the input limit and for input that is not valid UTF-8.

Postcode::isLegacy('900 108'); // true

Parameters

Name	Meaning
$input	Text from a user.

stateName()

public static function stateName(string $stateCode): ?string

Returns the English name of a state from its two-letter code. The lookup ignores the case of the ASCII letters only. It does not trim spaces or change other characters.

echo Postcode::stateName('fc'); // Federal Capital Territory

Parameters

Name	Meaning
$stateCode	A state code, such as EK.

precisionForAccuracy()

public static function precisionForAccuracy(?float $accuracyM): Precision

Returns the most precise segment that a GPS fix of this accuracy supports. Each limit in the spec is inclusive, so a fix equal to a limit gets the precision of that limit.

Postcode::precisionForAccuracy(35.0); // Precision::District

Parameters

Name	Meaning
$accuracyM	The accuracy radius in metres. Null, NaN, infinite and negative values mean that the accuracy is unknown, which gives the LGA.

truncate()

public function truncate(Precision $to): self

Shortens the postcode to a less precise segment, for example from a building to its area.

echo $postcode->truncate(Precision::District)->canonical; // EK-01-A03

Parameters

Name	Meaning
$to	The precision to keep. It must not be more precise than the code.

Throws

• InvalidArgumentException When $to is more precise than the code.

parent()

public function parent(): ?self

Returns the postcode one segment less precise, such as the area of a building.

echo $postcode->parent()?->canonical; // EK-01-A03-FK

contains()

public function contains(self $code): bool

Tells whether another postcode lies inside this one, such as a building inside its district. A postcode contains itself.

$district->contains($building); // true

Parameters

Name	Meaning
$code	The postcode to test.

redact()

public function redact(): string

Hides the unit, so that a log shows the area but not the building. A code without a unit stays as it is.

echo $postcode->redact(); // EK-01-A03-FK-**