packages/sql-semantics/src/Core/SemanticException.php

1<?php
2
3declare(strict_types=1);
4
5namespace SqlSemantics\Core;
6
7use RuntimeException;
8use SqlParser\Lexer\Token;
9use SqlParser\Parser\Node;
10use SqlSemantics\Statement\Element;
11
12/**
13 * An explicit semantic failure; callers must not treat a rejected tree as bound.
14 *
15 * @example Reading semantic facts
16 *     $source = new \SqlParser\Parser\Node('expr', 0, []);
17 *     $error = new \SqlSemantics\Core\SemanticException('unknown-column', 'Missing column', $source);
18 *     $error->reason // => 'unknown-column'
19 *
20 * @visibility public
21 */
22final class SemanticException extends RuntimeException
23{
24    /**
25     * @param string $reason Stable machine-readable failure code
26     * @param string $message Human-readable explanation
27     * @param Node|Token|Element $source Original syntax responsible for the failure
28     */
29    public function __construct(
30        public readonly string $reason,
31        string $message,
32        public readonly Node|Token|Element $source,
33    ) {
34        parent::__construct($message);
35    }
36}
37