- How do I install axlon/laravel-postal-code-validation in Laravel?
- Install it with composer require axlon/laravel-postal-code-validation. If package discovery is enabled there is nothing else to configure, and the two rules become available to FormRequest classes and Validator::make immediately. For Lumen or setups with discovery disabled, add Axlon\PostalCodeValidation\ValidationServiceProvider::class to your providers array.
- Does this package call Google's API at runtime?
- No. The README's reference to Google's libaddressinput describes where the postal code patterns came from, not a runtime dependency. The patterns are compiled into the package and evaluated in-process, so there is no network latency, no third-party uptime risk, and no address data leaving your application.
- What is the difference between postal_code, postal_code_with and postal_code_for?
- postal_code takes a fixed list of ISO 3166-1 alpha-2 country codes and requires the value to match at least one of them. postal_code_with takes field names and validates against whichever of those country fields is present, which suits billing versus shipping forms. postal_code_for is deprecated and will be removed in 4.0, so new code should use postal_code_with instead.
- Does it check that a postal code actually exists or is deliverable?
- It validates format only, so a syntactically valid code passes even if that code has never been assigned. If the requirement is address verification, deliverability or geocoding, this package is one layer of a two-layer solution rather than a replacement for an address verification service. Do not treat a passing rule as proof the address is real.
- Which Laravel and PHP versions are supported?
- The current release requires PHP 8.2 or greater and Laravel 12 or greater. In practice your application's Laravel and PHP versions are the binding constraint, and the package is rarely what blocks an upgrade. Compatibility with newer Laravel releases has largely been maintained through automated Laravel Shift pull requests and community contributions.
- How do I validate a postal code against a billing or shipping country field?
- Use postal_code_with with the paths to your country fields, for example postal_code_with:billing.country,shipping.country. Nested and wildcard paths such as addresses.*.country are supported, which covers most multi-address forms. Make sure the country field itself is validated as ISO 3166-1 alpha-2 and required on the same request, because the rule's correctness depends on it.
- What happens if the referenced country field is missing or null?
- postal_code_with only enforces the rule when at least one referenced country field is present, so a missing or empty country field causes the postal code to be skipped rather than rejected. Earlier releases had defects around this behaviour, so pin a recent version and add a regression test for the absent-country case. If a postal code must always be checked, pair the rule with a required country field.
- Which countries are supported, and what about countries without postal codes?
- Coverage comes from Google's libaddressinput data, so most countries with a postal system are supported. Territories without a conventional postal system, or that use non-ISO identifiers, are a known edge case and have needed explicit fixes in the past, such as the Canary Islands. Decide per country whether the rule should be skipped rather than enforced, and bear in mind that pattern drift can cause false negatives until a release updates the data.
- How do I set a custom error message or override a postal code pattern?
- You can supply a custom message through the messages array of your FormRequest or validator, exactly as with any native Laravel rule. If you need to correct a pattern, the PostalCodes facade exposes an override registry. Assign an owner to each override, cover it with tests, and retire it once an upstream release fixes the pattern so it does not silently mask regressions.
- Is this package safe to use in production and is it actively maintained?
- It is a thin, framework-native validation rule with no service, queue or datastore, and it has been consistently maintained across Laravel releases. The caveats are a single primary maintainer and no listed dependents, which is acceptable for a validation rule but argues for pinning a specific version and covering your country set with tests. Treat upgrades as routine maintenance rather than deferring them indefinitely.