Integration Laravel Package

Getting Started

1. Install the package and let Laravel's package discovery register the service provider:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Start with the new introduction block in the README — it gives the mental model for validators and rule IDs before you touch config.
3. First use case: define a validator with an explicit, stable rule ID and wire it into a form request. Rule IDs are now the stable handle you should key error messages, API responses, and tests against instead of class names or message strings.

class CreateUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'email', 'unique:users,email'],
        ];
    }

    public function messages(): array
    {
        // Reference the stable rule ID, not the message text.
        return [
            'email.unique' => __('validation.rule_ids.unique_email'),
        ];
    }
}

Implementation Patterns

• Use rule IDs as constants, not literals. Wrap IDs in a small enum or constants class so refactors and IDE navigation stay safe:

  enum RuleId: string {
      case UniqueEmail = 'unique_email';
      case StrongPassword = 'strong_password';
  }
  

• Map IDs to messages centrally. Keep a translation/config map from rule ID → human message and resolve it in a base FormRequest or exception handler. This keeps API error payloads consistent and translatable.
• API error envelopes. In app/Exceptions/Handler.php (or a dedicated ValidationException renderer), emit { "rule": "<stable-id>", "message": "..." }. Front-end clients can branch on the stable ID without parsing prose.
• Custom validators. Implement the package's validator contract and expose an id() (or equivalent) returning a stable string. Register it in the published config so the ID resolves during boot.
• Testing. Assert on rule IDs in feature tests (assertJsonPath('errors.0.rule', RuleId::UniqueEmail->value)) rather than on translated strings — this survives message edits and locale changes.
• Composition. For multi-rule fields, collect all failing rule IDs into an array in the error response so clients can render per-rule UI hints.
• CI guard. Add a test that asserts every registered validator returns a unique, non-empty ID — cheap insurance against accidental collisions or missing IDs.

Gotchas and Tips

• Stable IDs are a contract. Once an ID ships, treat renaming it as a breaking change for anything consuming your API. Add new IDs rather than repurposing old ones; document deprecations.
• Uniqueness is your responsibility. The package now exposes IDs but won't necessarily dedupe them across packages/validators. Namespace or prefix if you register third-party validators (e.g. billing.tax_id).
• Config caching. After publishing or editing the config that registers validators/IDs, run php artisan config:clear (and config:cache in production). Stale caches are the most common "my rule ID is missing" cause.
• Debugging. Dump the resolved ID map at boot (app(<Registry>::class)->all()) or add a small artisan command that lists registered validators and IDs — invaluable when an ID "isn't found."
• Message resolution order. If you both override messages() and use an ID→message map, be explicit about precedence; silent fallbacks to the package's default message are easy to miss.
• Extension points. The published config is the intended seam for registering validators and message maps; prefer it over service-container overrides so upgrades stay clean. If you need custom behaviour, extend the base validator rather than replacing it.
• README intro is worth reading once. The new introduction block clarifies the lifecycle of a validator (registration → resolution → message mapping), which explains most of the gotchas above.