Datavalidatorbundle Laravel Package

Getting Started

This package is a Symfony bundle at heart, so the first step for a Laravel developer is deciding how you're consuming it: standalone (pulling individual services out of the container) or via a Symfony kernel bridge. Most day-to-day use will be the constraint definition + validation command workflow, not the bundle wiring.

1. composer require <vendor>/<package>:1.0.0-ALPHA2 — pin the alpha explicitly; it's not stable yet.
2. Read the bundle's DependencyInjection/Configuration.php (or the README config block) first. As of ALPHA2 this is the source of truth for constraint definitions — you can now define constraints via a config parameter or tagged services instead of a YAML file, and the config tree is where the accepted keys live.
3. Check the validation command's signature (bin/console <prefix>:validate equivalent). Run it with -v immediately — ALPHA2 added verbose output listing each constraint before validating it plus timing and peak memory at the end. This is your fastest feedback loop.
4. First use case: define a single constraint via the config parameter, run the command in dry-run mode to confirm it's picked up, then run it for real.

If you're not running a Symfony kernel, the practical entry point is the constraint validator service itself — instantiate it through the container (or manually with its dependencies) and skip the command entirely. The command is a convenience wrapper, not a requirement.

Implementation Patterns

Config-parameter constraints (new in ALPHA2). Prefer this over YAML for Laravel projects — it maps cleanly onto config/*.php and lets you use env() for environment-specific constraint sets. Merge the bundle's config tree into a Laravel config file and bind it in a service provider. Watch precedence if you also have a legacy YAML file: pick one source and delete the other, because the resolution order between YAML, config parameter, and tagged services is not documented as stable in an alpha.

Tagged services for dynamic constraints. In Symfony you'd use !tagged_iterator. In Laravel, the equivalent is $this->app->tag([...], 'constraint') and $this->app->tagged('constraint'). This is the pattern to reach for when constraints are code (closures, tenant-specific rules, feature-flagged checks) rather than static configuration. Keep the tag name in a constant so the container wiring and the validator's collector don't drift.

Dry-run in CI, real run in deploy. The ALPHA2 fix to foreign-key constraint naming in dry-run mode means dry-run output is now trustworthy for FK-heavy schemas. Wire it into CI as a schema-drift check: dry-run, diff the output, fail the build on unexpected constraint changes. This is the single highest-value day-to-day pattern in the package.

Verbose output as your debugging tool. -v gives you constraint count, per-constraint names, wall time, and max memory. Use it to diagnose "why is validation slow" — the per-constraint name print tells you exactly which constraint hangs or thrashes. Note that max memory is process peak, so run the command in isolation if you want a meaningful number.

Graceful interruption for long runs. ALPHA2 handles SIGINT/SIGTERM so CTRL-C exits cleanly rather than leaving partial state. For long validation runs (large schemas, remote DBs), this means you can safely abort and rerun. Don't rely on it for transactional safety — it's a clean shutdown, not a rollback. If you're shelling out from a queue worker, send SIGTERM rather than SIGKILL so the handler gets a chance to run.

Exception handling. ALPHA2 introduced a common base exception for the bundle and aligned the API with Symfony Validator's exception hierarchy. Catch the bundle's base exception at the boundary (a console command, an HTTP controller) and let specific subclasses bubble to where you can act on them. Invalid constraint definitions now throw appropriate exceptions instead of whatever generic failure they used to produce — surface these at boot/compile time in a service provider so misconfiguration fails fast rather than at validation time.

Gotchas and Tips

• It's an alpha. 1.0.0-ALPHA2 can change exception types between patches. Pin the exact version and read the diff before bumping.
• Symfony bundle assumptions. There is no Laravel package discovery here. You will write the service provider yourself, and any bundle extension (ExtensionInterface, config tree processing) won't run unless you invoke it manually. Budget time for this; it's the main friction point for Laravel consumers.
• Exception API changed in ALPHA2. If you had catch blocks written against the pre-alpha exception class names, they will silently stop matching. Re-grep for catch around validation calls and retarget the new base class.
• Signal handling needs pcntl. The graceful CTRL-C behavior requires the pcntl extension. It's typically present in CLI SAPI on Linux, absent on Windows and sometimes stripped in minimal Docker images. Check php -m | grep pcntl in your runtime image; without it you get the old abrupt-exit behavior and no error.
• Verbose memory numbers are misleading in long-lived processes. If you invoke the validator from an Octane/queue worker, peak memory reflects the whole worker, not the validation. Run the command standalone for a real figure.
• Dry-run FK naming was broken pre-ALPHA2. Any dry-run output you cached or snapshot-tested against the old release will diff. Regenerate fixtures once, then treat dry-run output as stable again.
• Config-vs-YAML precedence is undocumented. If both are present, don't guess — test it. Better, remove the YAML file entirely so the question is moot.
• Extension point for custom constraints: tagged services is the intended hook, not subclassing the validator. Keeping constraints as discrete tagged classes makes them individually testable and lets the verbose output name them usefully.