Symfony Jsonrpc Params Sf Constraints Doc Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — the v2.0.2 release makes that explicit by changing the Composer type from library to symfony-bundle. Before you invest time, confirm which side of your stack you actually need:

1. Check what you're integrating with. The package's job is to derive JSON-RPC parameter documentation from Symfony Validator constraints (Assert\NotBlank, Assert\Type, Assert\Length, etc.) attached to your JSON-RPC param classes. It is a documentation layer on top of symfony/validator + the yoanm/symfony-jsonrpc-* family, not a standalone validator.
2. Install: composer require yoanm/symfony-jsonrpc-params-sf-constraints-doc. Inspect composer.json first (post-v2.0.2 it declares type: symfony-bundle) and the require block to see which yoanm/symfony-jsonrpc-* and symfony/* versions you're being pulled onto.
3. Register the bundle in config/bundles.php (or rely on Flex if you have a recipe). Look in src/ for the *Bundle class and its DependencyInjection/ extension — that extension is where the config key and service wiring live, and it's the fastest way to learn the real option names rather than trusting the README.
4. First use case: take one existing JSON-RPC method, annotate its params DTO with Symfony constraints, and dump the generated params documentation for that single method. Once that round-trips, expand to the whole method set.

Laravel reality check: there is no service provider and no package discovery here. In a Laravel app you can require symfony/validator and use constraints directly, but this bundle's DI wiring won't boot outside a Symfony kernel. If you're Laravel-first, either (a) run the doc generation in a small Symfony CLI/service and consume the JSON output, or (b) skip the bundle and read constraint metadata yourself via symfony/validator's ClassMetadataFactory.

Implementation Patterns

• Constraint-as-source-of-truth. Define param DTOs as plain classes, put Symfony constraints on properties, and let the bundle produce docs. This keeps validation and documentation from drifting — the main reason to adopt the package at all.
• Generate docs in CI, not at runtime. Emit the params doc as a build artifact (console command → JSON file) and commit or publish it. Runtime generation adds a cache-warming step and couples doc availability to container boot.
• Config-cache discipline. In Symfony, the DI extension's output is compiled. After changing constraints or bundle config, run bin/console cache:clear (and cache:warmup in deploy pipelines), or you'll debug a phantom.
• Documentation regression checks. Snapshot the generated JSON per method and diff it in CI. Constraint changes then surface as reviewable doc diffs rather than surprise API contract changes.
• Multi-version APIs. Keep separate config/param-DTO namespaces per API version and generate one doc set per version, rather than branching inside a single generator run.
• Laravel-side consumption. If Laravel is the consumer, expose the generated doc via an artisan-cached JSON file and serve it from a controller; treat the Symfony process as a build step, not a runtime dependency.
• Custom constraints. For domain-specific constraints, expect to register a mapper/normalizer so the generator knows how to render them — check the bundle's service definitions for the tag or interface it expects before writing your own.

Gotchas and Tips

• type: symfony-bundle is metadata, not magic. Existing installs keep working, but Flex/symfony/flex may now treat the package differently (bundle discovery, recipe lookup). If you previously installed it and pinned composer.lock, verify nothing re-resolves unexpectedly.
• Dependabot "prod-majors" bump. v2.0.2 also bumps two production dependencies by a major version. This is the actual risk in this release, not the type change. Run composer update --dry-run yoanm/symfony-jsonrpc-params-sf-constraints-doc (or composer why-not) to see whether those majors collide with your symfony/* or yoanm/* pins, and run your doc-generation step in CI before merging.
• No Laravel auto-discovery. Don't expect a ServiceProvider. php artisan vendor:publish will not find anything useful.
• Constraint coverage gaps. Not every Symfony constraint maps cleanly to a JSON-RPC param doc shape; nested/compound constraints and Assert\Callback are common blind spots. Test one constraint of each kind you rely on.
• Config key guessing. The bundle's config root is namespaced (yoanm_symfony_json_rpc_params_sf_constraints_doc by convention, but confirm in the DI extension). A wrong key is silently ignored unless you run with -vvv.
• Debugging knobs: bin/console debug:container <service-fragment>, bin/console debug:config <alias>, and -vvv on the generation command. Container debug tells you whether the bundle's services actually registered — that's the first thing to check when output is empty.
• Extension points are almost always (1) the constraint-mapper/normalizer service and (2) overriding the generator service in services.yaml. Both are safer than forking; forking means re-auditing on every 2.x bump.
• Doc output is not validation. This package documents constraints; it does not enforce them at the JSON-RPC boundary. Make sure the actual param validation path is wired separately, or you'll ship docs that promise checks the server never performs.