Framework Bundle Laravel Package

Getting Started

This package compiles declarative validation definitions into native Laravel rule sets. The 1.0.1 patch fixes a bug in the validation compiler itself, so treat 1.0.1 as the minimum usable version — 1.0.0 could emit incorrect rules, which is the worst class of bug in a validation library (silent under-validation).

Minimal steps:

1. composer require <vendor>/<package>^1.0.1
2. Publish config if the package ships one: php artisan vendor:publish --tag=<package>-config
3. Look first at the compiler entry point (usually src/Compiler.php or src/Validation/Compiler.php) and the config file — the config decides how definitions are mapped to rules, so it's the fastest way to understand the mental model.
4. First use case: take an existing FormRequest, move its rules() array into the package's declarative form, and compile it back inside rules().

public function rules(): array
{
    return ValidationCompiler::compile(StoreUserRequest::class);
}

Verify parity with your old rules before deleting them — dump the compiled output and diff it against the hand-written array. Given the compiler bug fixed in 1.0.1, do this comparison on the new version specifically.

Implementation Patterns

Compile inside rules(), not at boot. Keeping compilation in the request lifecycle means config and definition changes are picked up without a deploy step. If you need the speed, cache — but cache deliberately (see below).

Compile to an array, then hand off to Laravel. The value of this package is that the output is plain Laravel rules. Do not fight the framework afterward: use Rule:: objects, sometimes, bail, and closures exactly as you would normally. The compiler should be a source of rules, not a replacement for the validator.

Share definitions across requests. The strongest day-to-day win is defining a rule set once (per model, per DTO, per API resource) and compiling it into multiple form requests — store vs. update, API vs. web. Keep the definitions next to the thing they describe, not next to the request.

Layer contextual rules on top. Compile the base set, then merge request-specific additions:

return array_merge(
    ValidationCompiler::compile(UserDefinition::class),
    ['password' => ['required', 'confirmed', Password::defaults()]],
);

This keeps the compiler output stable and testable while still allowing per-endpoint variation.

Test the compiled output, not just the behaviour. A feature test proves the endpoint rejects bad input; a unit test asserting the compiled array proves the compiler did what you asked. The second catches regressions when you upgrade — which is exactly the failure mode 1.0.1 addressed.

Cache compiled rules in production only. Wrap compilation in Cache::remember() keyed by the definition class plus a version/config hash, and skip the cache in local/testing so edits take effect immediately.

Gotchas and Tips

Pin to ^1.0.1 and audit anything compiled under 1.0.0. The fix is described only as "Fixed validation compiler," which tells you the output was wrong but not which inputs triggered it. If you shipped 1.0.0, re-dump compiled rules for your most permissive and most complex definitions and compare against expectations. Pay attention to nested/array rules and conditional (sometimes, required_if) rules — those are the usual suspects in a compiler bug.

Beware silent under-validation. A broken compiler rarely throws; it emits fewer or looser rules. That means tests pass and bad data gets in. Add at least one assertion per compiled set that a known-invalid payload is rejected.

Rule ordering matters. bail, sometimes, and nullable are order-sensitive. If the compiler reorders keys or flattens nested arrays, behaviour changes subtly. When debugging a "rule isn't firing" report, dump the compiled array first — it's almost always ordering or a missing key rather than a Laravel quirk.

Pipe-delimited strings vs. arrays. If the compiler emits string rules ('required|max:255'), any rule argument containing a comma or a Rule:: object will break. Prefer array syntax throughout; check what the compiler actually produces before assuming.

Config changes need a cache bust. If compiled rules are cached and the cache key doesn't include the config hash, editing config in production changes nothing until the cache expires. Include a hash of relevant config in the key, or document a manual clear step.

Extension point: custom compilers/rules. Most packages of this shape expose a registry or a Compiler::extend()-style hook for custom rule types. Use it rather than forking — but register extensions in a service provider so they're active for queued jobs and console commands, not just HTTP requests.

Debugging workflow. Reproduce with a single definition, dump ValidationCompiler::compile(...), and compare against the equivalent hand-written array. If they match and validation still misbehaves, the problem is downstream in Laravel, not in the compiler — stop looking at the package.

Upgrade discipline. For a 1.x package whose compiler is still receiving correctness fixes, read every patch note and re-run your compiled-output unit tests on upgrade. Treat compiler output as part of your public contract.