Getting Started

Install the package with Composer and, if the service provider is not auto-discovered, register it in config/app.php.
Publish any package config (php artisan vendor:publish) before changing defaults, then php artisan config:clear.
Start with the new README introduction block — it should give the canonical install path, the minimum config, and the intended first example. Treat it as the source of truth for the happy path rather than copying snippets from older blog posts.
First use case: add one validator to a FormRequest, submit a failing payload, and inspect the validation response. Because validators now expose stable rule IDs, confirm the failure identifies the rule by ID rather than only by a message string.
Locate the rule ID reference (README, config, or an artisan command/listing if provided) before writing integration code, so you can key messages, logs, and client-side mappings off IDs from day one.

Implementation Patterns

Reference rules by ID, not by class name. Use the stable ID in config files, custom message arrays, and any allow/deny lists. IDs are intended to survive refactors of the underlying validator class.
Config-driven rule sets. Define which validators apply to which domain (e.g. per form or per API resource) in config, keyed by ID, and resolve them in a service or FormRequest. This keeps business policy out of controllers.
Message translation by ID. Map IDs to translation keys (validation.rules.<id>) so copy changes and localization do not touch rule registration.
Frontend parity. Expose the ID-to-message map (or the rule metadata) to your JS layer so browser-side validation and server-side validation stay aligned without duplicating wording.
API error envelopes. Return the rule ID alongside the field and message in 422 responses. Clients can branch on the ID instead of parsing prose.
Testing. Assert on the rule ID in validation failure tests rather than asserting on the human-readable message; message wording is presentation, IDs are contract.
Observability. Log or meter failures by rule ID to find which constraints reject the most traffic, without joining on message text.

Rule IDs are now a public contract. Renaming or recycling an ID is a breaking change for consumers keyed on it. Treat additions as safe and removals/renames as semver-major; audit downstream config before upgrading.
Watch for duplicate or colliding IDs when registering custom validators. Add a test or boot-time assertion that the ID set is unique.
ID vs class name drift. If you have existing code matching on validator class names, it will not automatically use IDs. Migrate deliberately and keep a mapping layer during transition.
Missing-ID fallbacks. Decide how unresolved IDs behave (throw vs. skip) and cover it in tests; silent skipping hides misconfiguration.
Cache invalidation. Rule/config changes need config:clear (and queue restarts if rules are resolved in workers). Stale config is the most common "the new validator isn't running" cause.
The README introduction is onboarding, not exhaustive. It is newly added and may lag behind edge-case behavior; verify advanced options against source or tests.
Debugging tip: dump the registered ID-to-validator map in a tinker session or a temporary route when a rule appears not to fire — confirm the ID you configured matches the ID actually registered.
Extension point: when adding your own validator, register a stable, namespaced ID (e.g. app.<domain>.<rule>) up front so third-party and first-party rules cannot collide.