PHPackages divineomega/php-postcodes - 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. [Validation & Sanitization](/categories/validation) 4. / 5. divineomega/php-postcodes Abandoned → [jord-jd/php-postcodes](/?search=jord-jd%2Fphp-postcodes)Library[Validation & Sanitization](/categories/validation) divineomega/php-postcodes ========================= This library handles various UK postcode related tasks such as address lookup by postcode, postcode validation, generation of valid UK postcodes and getting a postcode's outward and inward codes. v5.1.0(1mo ago)611.3k↓69.8%4[1 issues](https://github.com/Jord-JD/php-postcodes/issues)LGPL-3.0-onlyPHPPHP ^7.1||^8.0CI failing Since Jan 16Pushed 6mo agoCompare [ Source](https://github.com/Jord-JD/php-postcodes)[ Packagist](https://packagist.org/packages/divineomega/php-postcodes)[ Docs](https://github.com/Jord-JD/php-postcodes)[ GitHub Sponsors](https://github.com/DivineOmega)[ RSS](/packages/divineomega-php-postcodes/feed)WikiDiscussions master Synced 2w ago READMEChangelog (10)Dependencies (6)Versions (24)Used By (0) PHP Postcodes ============= [](#php-postcodes) [![Tests](https://github.com/Jord-JD/php-postcodes/actions/workflows/tests.yml/badge.svg)](https://github.com/Jord-JD/php-postcodes/actions/workflows/tests.yml)[![Packagist](https://camo.githubusercontent.com/18cd83cfe070fedfa73e11b893f3b5e6db9a396239c6b8a610cf23562f9194a5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6f72642d6a642f7068702d706f7374636f6465732e737667)](https://packagist.org/packages/jord-jd/php-postcodes/stats) This library handles various UK postcode related tasks. Features -------- [](#features) - Address lookup by postcode - Postcode validation - Generate valid UK postcodes - Get a postcode's outward and inward codes Installation ------------ [](#installation) To install, just run the following composer command. `composer require jord-jd/php-postcodes` Setup ----- [](#setup) ### Postcode Lookup Services [](#postcode-lookup-services) Using some of the data retrieval features provided by this library requires a postcode lookup service. It currently supports the following postcode lookup services. - [Ideal Postcodes](https://ideal-postcodes.co.uk) - [Loqate](https://www.loqate.com/) (the provider formerly known as Postcode Anywhere/PCA Predict) - [Postcodes.io](https://postcodes.io/) Ideal Postcodes and Postcode Anywhere can return individual premises. Postcodes.io only provides postcode-level geographic and administrative data, so its `getAddressesByPostcode()` implementation returns a single `Address` object for the postcode rather than a list of premises. Sign up at the respective website if you need to use these features. You can then use the following code to get an appropriate postcode lookup service object. ``` $postcodeLookupService = new \JordJD\Postcodes\Objects\IdealPostcodes('API_KEY'); // OR $postcodeLookupService = new \JordJD\Postcodes\Objects\PostcodeAnywhere('API_KEY'); // OR $postcodeLookupService = new \JordJD\Postcodes\Objects\PostcodesIo(); ``` Usage ----- [](#usage) ### Get addresses by postcode [](#get-addresses-by-postcode) To retrieve the addresses associated with a UK postcode, just pass it to the method shown below. You will receive an array of address objects, appropriately split by their address lines and other details. The number and detail of results depend on the lookup service. In particular, Postcodes.io always returns one postcode-level result; use a premises-capable provider when you need every deliverable address. ``` $addresses = $postcodeLookupService->getAddressesByPostcode('ST163DP'); ``` ### Validate postcode [](#validate-postcode) You can validate a UK postcode is correct using the `Validator` utility class. An example of how to do so is shown below. ``` $validated = \JordJD\Postcodes\Utils\Validator::validatePostcode('ST163DP'); ``` Please note that the postcode validation is case insensitive. You can also normalize user input to the conventional uppercase format. Invalid non-string or incomplete input returns `null`. ``` $postcode = \JordJD\Postcodes\Utils\Validator::normalizePostcode(" sw1a\t2aa "); // SW1A 2AA ``` ### Generate postcode [](#generate-postcode) This library allows you generate a random, valid UK postcode. This makes use of the `Generator` utility class, as shown below. ``` $postcode = \JordJD\Postcodes\Utils\Generator::generatePostcode(); ``` ### Get outward and inward codes [](#get-outward-and-inward-codes) > The first part of the Postcode eg PO1 is called the outward code as it identifies the town or district to which the letter is to be sent for further sorting. The second part of the postcode eg 1EB is called the inward code. ``` $outwardCode = \JordJD\Postcodes\Utils\Tokenizer::outward('ST163DP'); // Returns ST16 $inwardCode = \JordJD\Postcodes\Utils\Tokenizer::inward('ST163DP'); // Returns 3DP ``` HTTP clients and errors ----------------------- [](#http-clients-and-errors) Ideal Postcodes, Loqate and Postcodes.io use their current HTTPS JSON APIs. Each service accepts an optional Guzzle `ClientInterface` implementation as its second constructor argument, which is useful for custom timeouts, proxies, logging and tests. ``` $client = new \GuzzleHttp\Client(['timeout' => 10]); $service = new \JordJD\Postcodes\Objects\IdealPostcodes('API_KEY', $client); ``` Invalid postcodes throw `InvalidPostcodeException` before any API request is made. Provider authentication, HTTP and response errors continue to throw an exception with a descriptive message. Compatibility ------------- [](#compatibility) PHP 7.1 through the current PHP 8.x releases are supported. Composer selects a compatible maintained Guzzle and test-tool version for the PHP runtime in use. ### Health Score 54 — FairBetter than 97% of packages Maintenance76 Regular maintenance activity Popularity30 Limited adoption so far Community14 Small or concentrated contributor base Maturity78 Established project with proven stability Bus Factor1 Top contributor holds 83.8% 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 ~157 days Recently: every ~460 days Total 23 Last Release 31d ago Major Versions v1.2.1 → v2.0.02017-06-22 v2.2.0 → v3.0.02019-01-28 v3.0.1 → v4.0.02019-04-16 v4.6.0 → v5.0.02026-02-14 PHP version history (3 changes)v1.0.0PHP >=5.5.9 v4.0.0PHP ^7.1 v4.4.0PHP ^7.1||^8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/c580cdf7c14898fff179cdfc1085892091d5d2f49d917873a12365af9ac77c93?d=identicon)[Jord-JD](/maintainers/Jord-JD) --- Top Contributors [![Jord-JD](https://avatars.githubusercontent.com/u/650645?v=4)](https://github.com/Jord-JD "Jord-JD (31 commits)")[![kirsty-gasston](https://avatars.githubusercontent.com/u/12949343?v=4)](https://github.com/kirsty-gasston "kirsty-gasston (2 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (2 commits)")[![ash123456789](https://avatars.githubusercontent.com/u/11010491?v=4)](https://github.com/ash123456789 "ash123456789 (1 commits)")[![LNCH](https://avatars.githubusercontent.com/u/10821244?v=4)](https://github.com/LNCH "LNCH (1 commits)") --- Tags php-libraryphp-postcodespostcodepostcode-lookup-librarypostcode-validationuk-postcodephpPHP LibrarypostcodesPHP postcodes libraryPHP postcodes ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/divineomega-php-postcodes/health.svg) ``` [![Health](https://phpackages.com/badges/divineomega-php-postcodes/health.svg)](https://phpackages.com/packages/divineomega-php-postcodes) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k6.0M777](/packages/sylius-sylius)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k832.6k54](/packages/neuron-core-neuron-ai)[elgg/elgg Elgg is an award-winning social networking engine, delivering the building blocks that enable businesses, schools, universities and associations to create their own fully-featured social networks and applications. 1.7k17.3k100](/packages/elgg-elgg)[tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3661.3M49](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 353.6k](/packages/eslazarev-wildberries-sdk)[lion/bundle Lion-framework configuration and initialization package 132.4k5](/packages/lion-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)