bd-validation-rule

better-data: Adding a validation rule

For library maintainers introducing a new built-in validation rule (Rule\CreditCard, Rule\PhoneE164, Rule\StrongPassword, etc.). Rules are tiny, pure, attribute-decorated classes that the validator iterates per field. The contract is small but precise — getting it wrong (throwing instead of returning, applying to nulls, embedding side effects) breaks compositional rules and surfaces messy errors to consumers.

Misconception this skill corrects

"I'll throw an exception with the validation error message inside check() — easier than a return-string protocol."

The contract at src/Validation/Rule.php:25-28 is:

interface Rule
{
    public function check(mixed $value, string $fieldName, DataObject $subject): ?string;
}

null = pass, short error string = fail. Throwing is the engine's prerogative, not an individual rule's. The BuiltInValidator (src/Validation/BuiltInValidator.php) iterates rules across many fields and accumulates errors; an exception would short-circuit the entire validation pass and return a single error instead of the complete failure list — which is what ValidationResult is for.

Other AI-prone misconceptions:

• "Rule\Foo extends Rule\Email." Wrong — rules don't compose via inheritance; PHP's attribute reflection looks up exact class names. Add a new rule.
• "The interface is RuleInterface." Wrong — it's literally Rule. The AGENTS.md docs in older drafts referred to it as RuleInterface, but the actual file is src/Validation/Rule.php and the interface is Rule. Use that name.
• "Rules apply to null values too — I want to validate that ?Email $email = null is non-null." Wrong — convention is null means "skip"; if you want non-null, add #[Rule\Required] also. Single responsibility.

When to use this skill

Trigger when ANY of the following is true:

• Creating a new file under src/Validation/Rule/.
• The diff adds implements Rule (or implements the deprecated RuleInterface).
• Adding a new #[Rule\Foo] attribute to a DTO and you can't find Foo in src/Validation/Rule/.
• Reviewing a PR that throws inside a check() method — flag and convert to return-string.