Validation Bundle Laravel Package

Getting Started

Before you install anything, verify the dependency is even viable. The package is archived (last release 2017-04-07), has zero stars and zero dependents, and targets the Sulu 1.x / Symfony 2.8–3.x era. If you are on Sulu 2.x+, the schema-validation concerns this bundle addressed are handled inside Sulu core — do not add this bundle to a modern project. Confirm the target framework first:

composer show sulu/validation-bundle --all   # check available versions + requirements
composer require sulu/validation-bundle

Then read these four files, in order — they tell you everything about the package's surface area:

1. composer.json — PHP/Symfony/Sulu version constraints (this is your real compatibility matrix)
2. DependencyInjection/ — the bundle's extension class; shows which services it registers and what config keys exist
3. Validator/ (or Validation/) — the actual schema-validation implementation; this is the only code you'll call
4. Tests/ — the fastest way to see intended usage; copy a test setup rather than guessing

Register the bundle the Sulu-1.x way in app/AppKernel.php:

$bundles = [
    // ...
    new Sulu\Bundle\ValidationBundle\SuluValidationBundle(),
];

First use case to reach for: you accept an array (or a decoded JSON payload / form data) from a client and need to assert it matches a declared schema — required keys present, types correct, no unexpected fields — before it hits your persistence layer. Wire the validator service into a thin application service and call it at the top of your write path. Get one green test doing exactly that before you integrate it anywhere else.

Implementation Patterns

Inject the validator, don't instantiate it. The bundle exists to give you a container-managed service. Let autowiring (or an explicit alias in your services.yml) resolve it, and depend on it through a small wrapper of your own so that when you eventually replace the package you change one class instead of twenty.

final class ArticlePayloadValidator
{
    public function __construct(private object $schemaValidator) {}

    public function validate(array $payload): array
    {
        // returns violations/errors from the bundle's validator
        return $this->schemaValidator->validate($payload, $this->schema());
    }
}

The wrapper is not ceremony — it is the migration seam. Given the package's age, assume you will outgrow it.

Treat schemas as first-class artifacts. Whether the bundle reads PHP arrays, JSON files, or config, keep schemas in dedicated files (e.g. config/schemas/article.json) rather than inline literals. That gives you three wins: schemas become diffable in code review, they can be reused by frontend/API contract tests, and they can be handed to a JSON-Schema validator later without rewriting call sites.

Validate at the boundary, not in the entity. Schema validation is a request-shape concern. Put it in a controller listener, a command bus middleware, or the top of a service method — never inside Doctrine lifecycle callbacks. Schemas describe input; entities describe state. Conflating them produces validators that fire on fixture loading and migrations.

Convert violations to your transport's error format once. Whatever the bundle hands back, normalize it immediately into a single shape your API returns ({field: [messages]}). Two mapping functions — one for JSON APIs, one for Symfony forms — is all you should ever need:

// for form submissions
foreach ($violations as $v) {
    $form->get($v->getPropertyPath())?->addError(
        new FormError($v->getMessage())
    );
}

Compose with Symfony Validator rather than replacing it. The pragmatic pattern: use this bundle for structural/schema checks (shape, types, required keys) and Symfony's ValidatorInterface with constraint annotations for semantic rules (uniqueness, business invariants). Run schema validation first — it's cheap and catches malformed input before you touch the database.

Test with data providers over the schema itself. Because the schema is a file, you can enumerate its required fields and generate "missing field" test cases automatically. That keeps your test suite in sync as the schema evolves and catches the classic regression where someone adds a field to the schema but not the fixtures.

Gotchas and Tips

The archive status is the headline risk. With no maintainer, no security releases, and no dependents, there is nobody to file an issue with. Pin the exact version in composer.json, commit composer.lock, and do not rely on this package for anything on a security boundary. Budget a migration path from day one: the replacement is either Sulu core's own schema validation (2.x+) or a direct dependency on a maintained JSON-Schema validator plus Symfony Validator.

Zero dependents almost certainly means zero battle-testing. Expect rough edges in error messages, edge cases around nulls/empty arrays, and undocumented behavior. When something surprises you, read the validator source rather than searching the web — there will be no Stack Overflow answers.

Old-Symfony API drift is the most likely install failure. If the bundle's composer.json wants symfony/symfony ~2.8|~3.0 and you're on 4+, composer will either refuse or you'll --ignore-platform-reqs your way into fatal errors at runtime (removed Container::get() behavior, setExpectedException, ->getMock() signatures in its tests). Don't fight this; it's a hard stop signal.

Required-vs-nullable semantics are where schema validation goes wrong. Most schema implementations distinguish "key absent" from "key present but null." Decide explicitly which one your API means by "optional" and write a test for both cases — this is the single most common source of production 500s in schema-validated APIs.

Debug by dumping violations, not by reading logs. Schema validators tend to fail silently-ish (returning an empty array when you expected errors, because the schema itself was malformed or an unknown keyword was ignored). Validate a deliberately-bad payload in a tinker/console session and inspect the raw violation objects; if you get nothing, suspect the schema, not the data.

Localized messages won't come for free. Any translated error strings need a domain the bundle knows about. Check Resources/translations/ for the domain name and register your own overrides there rather than string-replacing messages in application code.

Extension points worth knowing: if the bundle exposes a tagged-service mechanism (a compiler pass collecting validators), that's the supported way to add custom rules — use it instead of subclassing the core validator. If it doesn't, the wrapper pattern above is your only clean extension route, which is another argument for writing the wrapper first.

Migration tip for the inevitable replacement: because you kept schemas in files and violations normalized in one place, swapping the engine is a one-file change. Write the wrapper as if the package were already gone — you'll thank yourself in six months.