Rule-based validation message replacers

[ragulka]

Laravel supports adding custom replacers, which are called when making replacements in validation error messages. This functionality, while still available, is no longer documented since version 8.x. It looks like extending the validator has been generally superseded by custom rule objects and closures.

However, some complex validation rules may still benefit from providing custom replacements. For example, consider a simple Contains rule which checks if an array contains all the required values. Ideally, the validation error would only list the missing values, ie:

$validator = Validator::make([
  'tags' => ['laravel', 'taylor'],
], [
  'tags' => [new Contains(['laravel', 'framework'])],
], [
  Contains::class => 'Some required tags are missing (:missing)',
])->errors();

Here, a custom validation error message is provided when creating the validator, and the message uses the :missing placeholder. While it is still possible register a replacer using Validator::replacer(), it's not optimal, since the replacer has no access to the failed rule instance, so it does not know which values were missing. Also, it splits the concerns of a single rule across different files, as Rule itself should not register custom replacers with the Validator (otherwise, a new replacer would be registered for each new rule).

As a solution, it would be great if the Rule class could provide a makeReplacements instance method, which could make the replacements for the message, while having access to all instance data. For example:

class Contains implements Rule, MakesReplacements
{
    protected array $missingValues = [];

    /**
     * Create a new rule instance.
     *
     * @return void
     */
    public function __construct(protected string|array $requiredValues = [])
    {
    }

    /**
     * Determine if the validation rule passes.
     *
     * @param  string  $attribute
     * @param  mixed  $value
     * @return bool
     */
    public function passes($attribute, $value): bool
    {
        $this->missingValues = [];

        if (is_array($value)) {
            foreach (Arr::wrap($this->requiredValues) as $requiredValue) {
                if (! in_array($requiredValue, $value, true)) {
                    $this->missingValues[] = $requiredValue;
                }
            }
        }

        return empty($this->missingValues);
    }

    /**
     * Get the validation error message.
     *
     * @return string
     */
    public function message(): string
    {
        return 'The :attribute is missing required values: :missing.';
    }

    public function makeReplacements(string $message, $attribute, $validator) : string
    {
        return str_replace(':missing', implode(', ', $this->missingValues), $message);
    }

This would require some changes in the FormatsMessages trait, as it does not pass the rule instance to its own makeReplacements method (which is public). I imagine something like this:

// Illuminate\Validation\Concerns\FormatsMessages

    /**
     * Replace all error message place-holders with actual values.
     *
     * @param  string  $message
     * @param  string  $attribute
     * @param  string|Rule  $rule
     * @param  array  $parameters
     * @return string
     */
    public function makeReplacements($message, $attribute, $rule, $parameters)
    {
        $message = $this->replaceAttributePlaceholder(
            $message, $this->getDisplayableAttribute($attribute)
        );

        $message = $this->replaceInputPlaceholder($message, $attribute);
        $message = $this->replaceIndexPlaceholder($message, $attribute);
        $message = $this->replacePositionPlaceholder($message, $attribute);

        if ($rule instanceof MakesReplacements) {
            return $rule->makeReplacements($message, $attribute, $this);
        } else if (isset($this->replacers[Str::snake($rule)])) {
            return $this->callReplacer($message, $attribute, Str::snake($rule), $parameters, $this);
        } elseif (method_exists($this, $replacer = "replace{$rule}")) {
            return $this->$replacer($message, $attribute, $rule, $parameters);
        }

        return $message;
    }