Structured validation¶
Attach validateSemantic() to a parser or use a Definition validator. Validation
runs lazily on accepted syntax, independently of reading semantic values.
Validators receive a ParseResult and may return:
trueor[]to accept;falsefor a defaultvalidation.failedissue;- a string for a
validation.failedissue with that message; - one
Result\ValidationIssue, or a list of them.
use Vanderlee\Comprehend\Result\ParseResult;
use Vanderlee\Comprehend\Result\ValidationIssue;
$age = $syntax->integer()->validateSemantic(
static fn(ParseResult $result): bool|ValidationIssue => (int) $result->rawText() <= 130
? true
: new ValidationIssue('age.range', 'Age exceeds 130', $result->span, ['maximum' => 130]),
);
$report = $age->parse('150')->validate();
foreach ($report->issues as $issue) {
echo $issue->code . ': ' . $issue->message;
}
An issue has immutable code, message, span and context properties. Codes
must be nonblank. Spans use byte offsets and must belong to the exact recognized
Source object; they may identify another field outside the validating parser's
span. Context accepts only finite JSON-compatible scalars, null and nested arrays.
It is copied recursively, including caller-owned references. Objects, resources,
recursive arrays and invalid UTF-8 context are rejected.
Children and accepted trivia contribute issues before enclosing validators.
Discarded alternatives contribute nothing. Validation does not retry a selected
alternative. Reports, issue objects and thrown validation exceptions are cached.
Malformed return values, associative issue arrays and foreign-source issues throw
UnexpectedValueException. Any issue blocks commit() and all selected effects.
ValidationResult derives valid from an empty issues list. Its constructor is
new ValidationResult($issues); the former boolean constructor and errors
property are removed. Replace message-only reads with
array_column($report->issues, 'message').
toArray(), toJson() and JsonSerializable expose only data:
{"valid":false,"issues":[{"code":"age.range","message":"Age exceeds 130","span":{"start":0,"end":3},"context":{"maximum":130}}]}
Issue serialization includes byte start/end coordinates, never the Source object. JSON encoding throws for non-UTF-8 message text, as with tree serialization.
Failed syntax produces syntax.rejected at the diagnostic byte offset. Explicit
recovery produces syntax.recovered issues over recovered regions, skips semantic
validators and refuses commit. There are no warning severities: every issue means
validation failed. See lifecycle and the runnable
validation example.