phdevutils/postal

Philippine ZIP/postal codes with zero-dependency lookup helpers. Joins to phdevutils/core cities/municipalities. Data from GeoNames (CC BY 4.0).

Maintainers

Package info

github.com/kon2raya24/ph-postal-php

pkg:composer/phdevutils/postal

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v0.2.0 2026-05-28 06:25 UTC

Requires

  • php: >=8.1

Requires (Dev)

MIT ebbe98bf255ae61a7ed892587a8f8b8ced5b4362

addresszipzipcodepostcodephilippinespostal-codefilipinopsgc

This package is auto-updated.

Last update: 2026-05-28 06:26:37 UTC

README

Packagist version npm version License: MIT

Philippine ZIP / postal codes with zero-dependency lookup helpers. Every ZIP joins to a PSGC city/municipality in phdevutils/core.

composer require phdevutils/postal

Usage

use PhDevUtils\Postal\PostalCodes;

// Find by ZIP — always returns a list (PH ZIPs are not unique)
PostalCodes::findByZip('1000');   // [['zip'=>'1000','cityMun'=>'Manila','cityMunCode'=>'133900','region'=>'13', ...]]
PostalCodes::findByZip('6000');   // Cebu City → cityMunCode '072217'

// Find by city name (case-insensitive), optional filter
PostalCodes::findByCity('Davao City');

// List / count, filter by { zip, cityMunCode, province, region }
PostalCodes::list(['region' => '13']);          // all NCR
PostalCodes::list(['cityMunCode' => '072217']);  // all Cebu City ZIPs
PostalCodes::count();                            // 2048
PostalCodes::count(['region' => '13']);          // 360

Each entry is an associative array:

[
  'zip'         => '1000',
  'cityMun'     => 'Manila',
  'cityMunCode' => '133900', // 6-digit PSGC parent (joins phdevutils/core), or null if unmatched
  'province'    => null,     // 4-digit, or null for NCR/HUC
  'region'      => '13',     // 2-digit
  'area'        => null,     // district/locality detail, or null
]

Joining to PSGC

use PhDevUtils\Address;

$zip  = PostalCodes::findByZip('6000')[0];
$city = Address::findCityMunicipality($zip['cityMunCode']); // ['name' => 'City of Cebu', 'province' => '0722', ...]

Notes

  • ZIPs are not unique; Metro Manila is district-level and rolls up to Manila city 133900.
  • ~6% of entries have cityMunCode null (barangay-level / spelling-variant places); they still carry region.

Data & attribution

Derived from GeoNames (CC BY 4.0) joined to PSA Q4 2024 PSGC, reconciled against the PHLPost locator. Community-sourced, not an official PHLPost feed — verify against PHLPost for production-critical use.

License

MIT (code). Bundled data © GeoNames, CC BY 4.0.