How pixelpeter/laravel-isocodes-validation works
This repository is a Laravel 10+ package, not a standalone application. Its job is to integrate the upstream IsoCodes validation library into Laravel’s validation system so developers can use rules like creditcard, zipcode, and isbn directly through Validator::make(...).
1. Core purpose
The package acts as an adapter layer between Laravel’s Validator component and the IsoCodes validators. The architecture is centered on translating Laravel validation rule strings into calls against IsoCodes classes and returning Laravel-style validation failures.
2. Primary runtime integration point
src/IsoCodesValidationServiceProvider.php is the package entry point for Laravel. It likely registers the custom validator extension and binds the package into the framework’s validation lifecycle. This is the main framework boundary.
3. Validation engine
src/IsoCodesValidator.php is the central domain class. It appears to encapsulate the rule execution logic: resolving which IsoCodes validator should be invoked, reading field values, handling optional references, and producing error messages in the format expected by Laravel.
4. Support layer for rule parsing and lookup
The src/Support directory contains helper components that split the validation concern into smaller responsibilities:
• Registry.php likely maps rule names to IsoCodes validator classes or metadata.
• ReferenceResolver.php likely extracts reference values from the input payload for rules that need context, such as zipcode:country.
• Replacer.php likely formats human-readable error messages by substituting field names, values, and reference values.
5. Handling of reference-based validations
A key architectural feature is support for validations that need another field as an input. The README examples show rules like zipcode:country and isbn:isbntype, so the validator must resolve cross-field dependencies before invoking IsoCodes. This is a distinct data flow: primary field value plus secondary reference value.
6. Nested arrays and dot notation
The package supports Laravel-style dot notation, including wildcard paths such as data.*.zipcode. The fixtures valid_with_dot_notation.php, invalid_with_dot_notation.php, and the corresponding reference-based fixtures indicate this is a first-class behavior. This means the validator must traverse nested array inputs and resolve references relative to each matched item.
7. Validation messages and localization
User-facing messages are stored in lang/en, lang/de, and lang/es. This indicates the package ships its own translation layer rather than relying entirely on Laravel defaults. The messages are meant to include the field value and, when relevant, the reference value, so the Replacer component is likely important to message rendering.
8. Package boundaries and dependencies
The repository is a Composer package (composer.json) with a small internal surface area and an external dependency on the IsoCodes library and Laravel’s validation APIs. The package does not expose HTTP controllers, queues, or persistence layers; its boundary is strictly validation-time logic inside a Laravel app.
9. Test architecture
Tests live under tests/Unit, with a focused unit test for the validator and a separate test for reference resolution. The tests/fixtures directory provides sample payloads for valid/invalid cases, dot notation, and reference-based rules, which suggests the test strategy emphasizes behavioral coverage over broad integration tests.
10. Quality and release tooling
The repository includes GitHub Actions for tests, PHPStan static analysis, code style fixing, changelog updates, and Dependabot auto-merge. These workflows indicate a mature library maintenance setup, but they do not affect runtime architecture directly.
11. Versioning and compatibility focus
The README emphasizes Laravel 10+ compatibility. That suggests the package is built around modern Laravel validation extension points and expects PHP/Laravel conventions rather than supporting older framework hooks.
12. What an architecture diagram should show
A good diagram would have:
• Laravel application code calling Validator::make(...)
• Laravel’s validation subsystem invoking this package’s custom rule handler
• IsoCodesValidator as the core dispatcher
• Registry, ReferenceResolver, and Replacer as internal support components
• IsoCodes library as the external validation engine
• Language files as the source of localized error text
• Tests and CI as supporting quality systems around the package
Overall, the architecture is a thin but carefully structured adapter: Laravel input and rule strings flow into the package, support classes resolve references and formatting, and the actual ISO-specific checks are delegated to the external IsoCodes library.
Main entry points: IsoCodesValidator.php IsoCodes validator · Replacer.php Replacer · IsoCodesValidatorTest.php Validator tests · ReferenceResolverTest.php Resolver tests
Components 14
Runtime
Laravel validation integration and core adapter
- Service provider · Registers the custom validation extension
src/IsoCodesValidationServiceProvider.php - IsoCodes validator · Dispatches rules, resolves values, and returns failures
src/IsoCodesValidator.php
Support
Rule lookup, reference resolution, and message formatting
- Registry · Maps rule names to IsoCodes validators
src/Support/Registry.php - Reference resolver · Finds secondary field values for contextual rules
src/Support/ReferenceResolver.php - Replacer · Builds Laravel-style validation messages
src/Support/Replacer.php
Localization
Translated validation messages
- English messages · Default validation text
lang/en/validation.php - German messages · Localized validation text
lang/de/validation.php - Spanish messages · Localized validation text
lang/es/validation.php
Quality
Tests and automation around the package
- Validator tests · Covers rule execution and message behavior
tests/Unit/IsoCodesValidatorTest.php - Resolver tests · Covers reference lookup behavior
tests/Unit/Support/ReferenceResolverTest.php - Fixtures · Sample payloads for valid, invalid, dot notation, and references
tests/fixtures/valid_with_dot_notation.php
External
Framework and library dependencies
- Laravel app · Host application using Validator::make(... )
- Validator · Laravel validation subsystem
- IsoCodes · Upstream validation engine
Connections 14
- Laravel app → Validator: validate data · Application invokes Laravel validation
- Validator → Service provider: extension hook · Framework uses the package's custom rule registration
- Service provider → IsoCodes validator: registers · Provides the validator implementation to Laravel
- IsoCodes validator → Registry: resolve rule · Looks up the IsoCodes validator for each rule
- IsoCodes validator → Reference resolver: resolve reference · Reads secondary field values for contextual rules
- IsoCodes validator → Replacer: format error · Prepares Laravel-compatible failure messages
- IsoCodes validator → IsoCodes: delegate check · Runs the underlying ISO-specific validation
- Replacer → English messages: default text · Uses English message templates
- Replacer → German messages: localized text · Uses German message templates
- Replacer → Spanish messages: localized text · Uses Spanish message templates
- Validator tests → IsoCodes validator: covers · Validates core adapter behavior
- Validator tests → Fixtures: uses · Loads sample payloads and rule cases
- Resolver tests → Reference resolver: covers · Validates cross-field reference lookup
- Resolver tests → Fixtures: uses · Loads nested and reference-based payloads