[Feature Request] Allow RuleTransformers to enrich property descriptions instead of being overwritten by PHPDoc

[romalytvynenko]

Discussed in #1164

^{Originally posted by squiaios May 21, 2026}

Description :

Context

Currently, when a property in a FormRequest has both a PHPDoc description and a custom RuleTransformer that sets a description, the PHPDoc description takes precedence and completely overwrites the one provided by the RuleTransformer.

This happens in SchemaBagToParametersTransformer where PhpDocSchemaTransformer is called after the initial schema generation, replacing the description.

The Problem

In many cases, a RuleTransformer provides technical details about a specific validation rule (e.g., "Must be a valid SIRET (14 digits)"), while the PHPDoc provides functional context (e.g., "The repairer's SIRET").

We often want both informations in the final OpenAPI document, but currently, we have to choose one or implement complex DocumentTransformers to manually merge them.

Example

/**
 * Repairer's SIRET
 */
'repairer_siret' => ['required', new \App\Rules\Siret],

And the transformer:

public function toSchema(Type $previous, NormalizedRule $rule, RuleTransformerContext $context): Type
{
    $description = $previous->description ? $previous->description . ' ' : '';
    $description .= PHP_EOL . 'Must be a valid SIRET (14 digits)';

    return $previous->setDescription(trim($description));
}

Actual output: "Repairer's SIRET"
Desired output: "Repairer's SIRET. Must be a valid SIRET (14 digits)"

Proposed Solution

It would be great if Scramble could provide a way to "append" or "enrich" the description instead of just replacing it.