Jsonrpc Params Symfony Constraint Doc Sdk Laravel Package

Getting Started

This package is a bridge, not a standalone tool. It converts Symfony Validator constraints (Assert\NotBlank, Assert\Type, Assert\Length, …) attached to your JSON-RPC params DTOs into a documentation array consumable by the yoanm/jsonrpc-* doc tooling. If you aren't already using the Yoanm JSON-RPC server/doc stack, this package adds little on its own — the value is in keeping validation rules and generated API docs from a single source of truth.

Minimal steps:

composer require yoanm/jsonrpc-params-symfony-constraint-doc-sdk

Where to look first:

1. src/ — find the resolver/normalizer that maps a Constraint instance to a doc array. That class is the whole package.
2. tests/ — the test suite is the de-facto specification; it enumerates exactly which constraints and which options are supported.
3. The README's usage snippet — usually shows injecting the resolver into the Yoanm doc generator.

First use case: annotate a params DTO, wire the resolver into your doc generation, and confirm the generated markdown/JSON shows type, required, minLength, etc.

final class UserCreateParams
{
    /** @Assert\NotBlank */
    /** @Assert\Type("string") */
    /** @Assert\Length(min=2, max=64) */
    public string $name;

    /** @Assert\Type("integer") */
    /** @Assert\Range(min=0, max=150) */
    public ?int $age = null;
}

Implementation Patterns

One DTO per method, constraints as the contract. The idiomatic flow is: JSON-RPC method declares a params DTO, the server validates the DTO with Symfony Validator, and the doc generator reads the same DTO's constraints. Never hand-write param docs separately — that drifts immediately.

Wire the resolver into doc generation, not validation. This package only reads constraints. Validation remains standard Symfony:

$violations = $validator->validate($paramsDto);

The doc side is where you plug in the SDK's resolver when building the method's params documentation node.

Custom constraints need a custom resolver. For domain-specific constraints (Assert\CurrencyCode, custom Constraint subclasses, Assert\Choice callbacks), you'll write a small resolver and register it alongside the built-in ones. Look at how the package's own resolvers are tagged/registered — that's your extension template.

Test the doc output, not just the constraint. Snapshot the generated doc array per method so that adding/removing a constraint is visible in diffs. This is your only real defense against silent gaps in the doc.

Keep optionality explicit. ?Type / nullable properties typically translate to "not required"; a non-nullable property with NotBlank translates to "required". Be deliberate about which signal you rely on, and verify both cases against the generated output before shipping.

Gotchas and Tips

• Coverage is partial by design. Only a subset of Symfony constraints map cleanly to JSON-Schema-ish doc constructs. Assert\Valid, Assert\All, Assert\Collection, Assert\Callback, and conditional constraints (When, Expression) generally do not map 1:1. Check tests/ for the authoritative list before assuming a constraint is documented.
• Unknown constraints are silently skipped. There is almost certainly no error when a constraint has no resolver. Debug by dumping the intermediate doc array for a single method rather than diffing the final rendered markdown, which is too lossy.
• Constraint options are not all honored. E.g. Length maps min/max well, but combined options, groups, and payload metadata may be ignored. Assert on the exact expected doc shape in tests rather than "looks right."
• Validation groups leak into docs. If your DTO uses validation groups, constraints from all groups may appear in the doc. If you document per-scenario, you may need separate DTOs or a filtering resolver.
• Pin the version and keep a contract test. This is a zero-star, single-maintainer package with no dependents — treat it as internal glue. composer require with an exact constraint, and have a test that fails if a package update changes your generated doc output.
• Order of annotations can matter for compound constraints if resolvers are applied sequentially; keep related constraints grouped on the same property and re-check output after reordering.
• Extend via new resolvers, not by forking. If you need Assert\Choice → enum, add a resolver and register it; forking the SDK will make upstream diffs painful on the next release.
• Cross-check against runtime validation. Write one integration test that feeds an invalid payload and confirms both (a) Symfony rejects it and (b) the generated doc advertises the same rule. That test catches mapping bugs that neither layer catches alone.