# pixelpeter/laravel-isocodes-validation architecture

> Architecture diagram of the GitHub repository pixelpeter/laravel-isocodes-validation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pixelpeter/laravel-isocodes-validation
- Repository: https://github.com/pixelpeter/laravel-isocodes-validation

## Overview

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: [`src/IsoCodesValidator.php`](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/IsoCodesValidator.php) (IsoCodes validator), [`src/Support/Replacer.php`](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/Replacer.php) (Replacer), [`tests/Unit/IsoCodesValidatorTest.php`](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/IsoCodesValidatorTest.php) (Validator tests), [`tests/Unit/Support/ReferenceResolverTest.php`](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/Support/ReferenceResolverTest.php) (Resolver tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_service_provider["Service provider<br/>package entrypoint"]
  node_validator_core["IsoCodes validator<br/>adapter core"]
end

subgraph group_support["Support"]
  node_registry["Registry<br/>rule map<br/>[Registry.php]"]
  node_reference_resolver["Reference resolver<br/>input resolver"]
  node_replacer["Replacer<br/>message formatter<br/>[Replacer.php]"]
end

subgraph group_localization["Localization"]
  node_messages_en["English messages<br/>translation<br/>[validation.php]"]
  node_messages_de["German messages<br/>translation<br/>[validation.php]"]
  node_messages_es["Spanish messages<br/>translation<br/>[validation.php]"]
end

subgraph group_quality["Quality"]
  node_validator_tests["Validator tests<br/>unit test"]
  node_resolver_tests["Resolver tests<br/>unit test"]
  node_fixtures["Fixtures<br/>test data"]
end

subgraph group_external["External"]
  node_laravel_app["Laravel app<br/>consumer"]
  node_laravel_validator["Validator<br/>framework API"]
  node_isocodes_lib["IsoCodes<br/>external library"]
end

node_laravel_app -->|"validate data"| node_laravel_validator
node_laravel_validator -->|"extension hook"| node_service_provider
node_service_provider -->|"registers"| node_validator_core
node_validator_core -->|"resolve rule"| node_registry
node_validator_core -->|"resolve reference"| node_reference_resolver
node_validator_core -->|"format error"| node_replacer
node_validator_core -->|"delegate check"| node_isocodes_lib
node_replacer -->|"default text"| node_messages_en
node_replacer -->|"localized text"| node_messages_de
node_replacer -->|"localized text"| node_messages_es
node_validator_tests -->|"covers"| node_validator_core
node_validator_tests -->|"uses"| node_fixtures
node_resolver_tests -->|"covers"| node_reference_resolver
node_resolver_tests -->|"uses"| node_fixtures

click node_service_provider "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/IsoCodesValidationServiceProvider.php"
click node_validator_core "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/IsoCodesValidator.php"
click node_registry "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/Registry.php"
click node_reference_resolver "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/ReferenceResolver.php"
click node_replacer "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/Replacer.php"
click node_messages_en "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/en/validation.php"
click node_messages_de "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/de/validation.php"
click node_messages_es "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/es/validation.php"
click node_validator_tests "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/IsoCodesValidatorTest.php"
click node_resolver_tests "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/Support/ReferenceResolverTest.php"
click node_fixtures "https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/fixtures/valid_with_dot_notation.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_service_provider,node_validator_core toneBlue
class node_registry,node_reference_resolver,node_replacer toneAmber
class node_messages_en,node_messages_de,node_messages_es toneMint
class node_validator_tests,node_resolver_tests,node_fixtures toneRose
class node_laravel_app,node_laravel_validator,node_isocodes_lib toneIndigo
```

## Components

### Runtime

Laravel validation integration and core adapter

- [Service provider](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/IsoCodesValidationServiceProvider.php): package entrypoint · Registers the custom validation extension · `src/IsoCodesValidationServiceProvider.php`
- [IsoCodes validator](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/IsoCodesValidator.php): adapter core · Dispatches rules, resolves values, and returns failures · `src/IsoCodesValidator.php`

### Support

Rule lookup, reference resolution, and message formatting

- [Registry](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/Registry.php): rule map · Maps rule names to IsoCodes validators · `src/Support/Registry.php`
- [Reference resolver](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/ReferenceResolver.php): input resolver · Finds secondary field values for contextual rules · `src/Support/ReferenceResolver.php`
- [Replacer](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/src/Support/Replacer.php): message formatter · Builds Laravel-style validation messages · `src/Support/Replacer.php`

### Localization

Translated validation messages

- [English messages](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/en/validation.php): translation · Default validation text · `lang/en/validation.php`
- [German messages](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/de/validation.php): translation · Localized validation text · `lang/de/validation.php`
- [Spanish messages](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/lang/es/validation.php): translation · Localized validation text · `lang/es/validation.php`

### Quality

Tests and automation around the package

- [Validator tests](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/IsoCodesValidatorTest.php): unit test · Covers rule execution and message behavior · `tests/Unit/IsoCodesValidatorTest.php`
- [Resolver tests](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/Unit/Support/ReferenceResolverTest.php): unit test · Covers reference lookup behavior · `tests/Unit/Support/ReferenceResolverTest.php`
- [Fixtures](https://github.com/pixelpeter/laravel-isocodes-validation/blob/master/tests/fixtures/valid_with_dot_notation.php): test data · Sample payloads for valid, invalid, dot notation, and references · `tests/fixtures/valid_with_dot_notation.php`

### External

Framework and library dependencies

- **Laravel app**: consumer · Host application using Validator::make(... )
- **Validator**: framework API · Laravel validation subsystem
- **IsoCodes**: external library · Upstream validation engine

## Connections

- 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
