Getting Started

Install with Composer; Laravel package auto-discovery should register the service provider. If the package publishes config, publish it and review the default validator/rule-ID map before writing application rules.
Read the README introduction first (added in v1.0.1). It should explain the validator model and the new stable rule ID contract; use that as the source of truth for whether IDs are accepted directly in rules arrays or are only metadata for messages/error codes.
Find the validator registry, rule classes, and tests/examples. Confirm how a rule ID maps to its validator implementation and how validation messages are resolved.
First use case: add one rule ID to a FormRequest rules array, assert a passing and failing payload at the HTTP layer, then map the same ID to a custom validation message or API error code.

Implementation Patterns

Prefer stable rule IDs over class names in application code where the package supports it. This keeps form requests, config-driven rule sets, and client-facing validation metadata decoupled from validator class names.
Maintain a central rule-ID map for messages, localization keys, and API error codes. Use the same IDs in backend validation and front-end validation hints so clients can react to specific failures without string matching.
Compose rule sets per form request or action, including conditional rules (sometimes, required_if, etc.). Reuse IDs in shared rule sets for create/update flows rather than duplicating validator class references.
Register custom validators once, assign immutable IDs, and cover them with feature tests at the HTTP boundary. Test both the ID-to-validator resolution and the ID-to-message resolution.
Use IDs when formatting validation exceptions or API responses. If the package exposes a registry, consider exposing a read-only list of supported IDs to internal consumers.
Adopt stable IDs incrementally: start with new validators and high-value shared rules, then migrate existing rules only where the package clearly supports ID-based references.

Treat rule IDs as public API. Renaming or removing an ID is a breaking change for configs, clients, and error-code mappings; add aliases or new IDs instead of silently renaming.
Watch for ID collisions across packages/providers. Prefix IDs by domain or package, and verify registration order if multiple providers add validators.
Do not assume a stable rule ID is the same string Laravel expects in a rules array. Check the README and tests to confirm whether the package resolves IDs or whether IDs are only for messages/error metadata.
Clear cached config after changing validators or ID mappings (php artisan config:clear), and test with the same cache settings used in production.
Debug by inspecting the validator registry/rule map and writing tests that assert ID → validator and ID → message separately. This isolates registration problems from message-resolution problems.
Extension points are typically custom validators, rule objects, and macros. Keep IDs stable when rule semantics change; if behavior changes materially, introduce a new ID rather than changing the meaning of an existing one.