PHPackages chisnall/postcode - 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. chisnall/postcode ActiveLibrary[Validation & Sanitization](/categories/validation) chisnall/postcode ================= Postcode validator for Laravel v1.0.1(6mo ago)08MITPHPPHP ^8.0 Since Nov 16Pushed 6mo agoCompare [ Source](https://github.com/chisnall/postcode)[ Packagist](https://packagist.org/packages/chisnall/postcode)[ RSS](/packages/chisnall-postcode/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (1)Versions (3)Used By (0) Laravel Postcode Validator ========================== [](#laravel-postcode-validator) A postcode validator for Laravel. Handles UK postcodes including the Isle of Man and the Channel Islands. Designed to be used with Laravel's built-in form validation but also supports manual usage. It works with Laravel versions 10 to 12. [![screenshot](https://github.com/chisnall/postcode/raw/main/screenshot.png "Screenshot")](https://github.com/chisnall/postcode/blob/main/screenshot.png) Features -------- [](#features) - Checks postcode against an external API - Uses ONS and Ordnance Survey postcode data - Determines postcode country - Supports England, Wales, Scotland and Northern Ireland - Supports the Isle of Man and the Channel Islands - Falls back to regex validation if the external API is unavailable - Allows countries or areas to be excluded Installation ------------ [](#installation) Install with composer: ``` composer require chisnall/postcode ``` Status Codes ------------ [](#status-codes) Status CodeForm validationDescription200N/AThe postcode is valid.403`postcode.excluded`The postcode is excluded by country or area.404`postcode.not_found`The postcode was not found.422`postcode.not_valid`The postcode format is not valid.503`postcode.service_error`The external API is not valid.Usage - Form Validation ----------------------- [](#usage---form-validation) The form validation messages can be customised from the status code returned. There is a catch-all message: `input.postcode` However, it is recommended to use the status code specific messages. This provides a better user experience. Use this in the controller which handles the form submission: ``` $validated = $request->validate([ 'input' => 'required|postcode', ], [ 'input.required' => 'Please enter your postcode.', 'input.postcode' => 'This will catch all errors if specific status codes are not handled.', 'input.postcode.excluded' => 'The postcode or area is excluded.', 'input.postcode.not_found' => 'The postcode is not found.', 'input.postcode.not_valid' => 'The postcode format is not valid.', 'input.postcode.service_error' => 'The external API is unavailable and regex fallback is disabled.', ]); ``` The priority in which the form messages are shown is: 1. Specific status code message (if defined) 2. The catch-all message (if defined) 3. Default system message Configuration ------------- [](#configuration) The default configuration can be changed using ENV variables. You may not be legally able to provide your services to certain countries. Or you ship physical goods and the shipping cost is prohibitive to certain areas. In these cases you can exclude countries or areas. For form validation, this is done in the global configuration though ENV variables. ENV VariableDefaultDescription`POSTCODE_API_ENDPOINT`The URL of the external API.`POSTCODE_REGEX_FORCE`falseForce regex. Disables the external API.`POSTCODE_REGEX_FALLBACK`trueFallback to regex if external API is down.`POSTCODE_EXCLUDE_COUNTRIES`nullComma separated list of countries to exclude.`POSTCODE_EXCLUDE_AREAS`nullComma separated list of areas to exclude.Notes 1. If you want to test the 503 service error, set the API endpoint so it is unreachable. For example, a path in localhost. 2. The list of countries to exclude is case-insensitive. 3. The list of areas to exclude is also case-insensitive. 4. The area is the first part of the postcode. For example, `SW1A 1AA` is in the area `SW`. Usage - Manual -------------- [](#usage---manual) Validation can be done manually as a facade pattern. Each facade call generates a new instance rather than reusing a cached one. Global configuration from the ENV variables still applies when using the facade, but can be overridden using the facade methods. Basic usage: ``` $postcode = Postcode::lookup('SW1A 1AA'); ``` That will return an instance of the postcode object. These methods are available and can be chained: MethodInputDescription`excludeAreas`string or arrayAdd an area to the exclude list.`excludeCountries`string or arrayAdd a country to the exclude list.`forceRegex`null, true or falseForce regex. Defaults to true if no input.`includeAreas`string or arrayForce include an area already excluded.`includeCountries`string or arrayForce include a country already excluded.`lookup`stringPerform the postcode lookup. Do this after the other methods.`toArray`N/AConvert result to array. Use at the end of the chain.For example: ``` $postcode = Postcode::forceRegex()->lookup('SW1A 1AA')->getStatus(); ``` These getters are available: MethodReturnsDescription`getPostcode`stringThe postcode used for the lookup.`getArea`stringThe area used for the lookup.`getApiEndpoint`stringThe API endpoint used.`getApiCall`boolIf the API was used.`getApiError`null or stringThe API error.`getRegexUsed`boolIf regex was used.`getRegexForced`boolIf regex was forced.`getExcludeAreas`arrayArray of excluded areas.`getExcludeCountries`arrayArray of excluded countries.`getStatus`intThe lookup status code.`getResult`arrayArray of the lookup result.`getError`null or stringThe lookup error.The `getResult` method returns an array with the following keys: KeyTypeDescription`postcode`stringThe postcode in the correct format.`admin_district`stringThe admin (council) area.`country`stringThe country.The admin district is "unknown" if the regex service is used. Regex Fallback -------------- [](#regex-fallback) If the external API is unavailable, the regex fallback will be used, unless disabled. The regex can also be forced, which will disable the external API. Caveats regarding the regex service: 1. Unable to determine if a postcode actually exists. Only if the format is correct. 2. Unable to determine the admin district. Always returns "unknown". 3. Cannot reliably determine a country. This uses the area part of the postcode and some postcode areas overlap countries. For example: CH (Chester) - overlaps England and Wales. SY (Shrewsbury) - overlaps England and Wales. TD (Galashiels) - overlaps Scotland and England. This is where the external API should be used to reliably determine if the postcode actually exists and to get the correct country. Publish ------- [](#publish) The configuration can be published to allow further customisation. `artisan vendor:publish --tag=postcode-config` The translations can be published to allow further customisation. `artisan vendor:publish --tag=lang` ### Health Score 32 — LowBetter than 72% of packages Maintenance69 Regular maintenance activity Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity41 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 183d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/49f92c6ddbf60ba32df1ba659eb598ce61ff07a920c0a727758a561e97e58858?d=identicon)[Lee C](/maintainers/Lee%20C) --- Top Contributors [![chisnall](https://avatars.githubusercontent.com/u/155248915?v=4)](https://github.com/chisnall "chisnall (2 commits)") --- Tags laravelvalidationaddresspostcodeuk ### Embed Badge ![Health badge](/badges/chisnall-postcode/health.svg) ``` [![Health](https://phpackages.com/badges/chisnall-postcode/health.svg)](https://phpackages.com/packages/chisnall-postcode) ``` ### Alternatives [crazybooot/base64-validation Laravel validators for base64 encoded files 1341.9M8](/packages/crazybooot-base64-validation)[galahad/laravel-addressing Laravel package providing addressing functionality 70316.6k](/packages/galahad-laravel-addressing)[johnpaulmedina/laravel-usps USPS Addresses API v3 (OAuth2) for Laravel 2622.6k](/packages/johnpaulmedina-laravel-usps)[carsdotcom/laravel-json-schema Json Schema validation for Laravel projects 1036.7k3](/packages/carsdotcom-laravel-json-schema) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)