packages/ztd-query-core/src/Rewrite/SqlRewriter.php

1<?php
2
3declare(strict_types=1);
4
5namespace ZtdQuery\Rewrite;
6
7use ZtdQuery\Exception\UnknownSchemaException;
8use ZtdQuery\Exception\UnsupportedSqlException;
9use ZtdQuery\Sql\TransactionStatement;
10
11/**
12 * Turns a statement into the plan ZTD will carry out instead of it.
13 *
14 * Every dialect reads its own SQL, so each database package implements this;
15 * what the session does with the answer is the same whichever one it came
16 * from. Two things an implementation may refuse are part of the contract
17 * rather than accidents of it: a statement ZTD cannot simulate, and a table
18 * nothing has told it about. The session decides what to do about each,
19 * because what should happen is a matter of configuration.
20 */
21interface SqlRewriter
22{
23    /**
24     * Answers the transaction statement a statement is, if it is one.
25     *
26     * @param string $sql Statement as it was written
27     *
28     * @return TransactionStatement|null What it does to the transaction, or null when it is not one
29     */
30    public function transactionStatement(string $sql): ?TransactionStatement;
31
32    /**
33     * Answers a SELECT this dialect accepts and that yields no rows.
34     *
35     * @return string The statement
36     */
37    public function emptyResultSelect(): string;
38
39    /**
40     * Splits a batch into the statements it is written as.
41     *
42     * Splitting is lexical: a semicolon inside a string, a comment or a
43     * dollar-quoted body does not end a statement, and which of those exist is
44     * a property of the dialect.
45     *
46     * @param string $sql Batch as it was written
47     *
48     * @return list<string> The statements, in the order they were written
49     */
50    public function splitStatements(string $sql): array;
51
52    /**
53     * Answers the plan for a statement, or for the first of a batch.
54     *
55     * @param string $sql Statement as it was written
56     *
57     * @return RewritePlan What ZTD will carry out instead of it
58     *
59     * @throws UnsupportedSqlException When ZTD cannot simulate the statement
60     * @throws UnknownSchemaException When the statement names a table nothing has described
61     */
62    public function rewrite(string $sql): RewritePlan;
63
64    /**
65     * Answers a plan for each statement of a batch.
66     *
67     * @param string $sql Batch as it was written
68     *
69     * @return MultiRewritePlan What ZTD will carry out instead of each of them
70     *
71     * @throws UnsupportedSqlException When ZTD cannot simulate one of the statements
72     * @throws UnknownSchemaException When one of them names a table nothing has described
73     */
74    public function rewriteMultiple(string $sql): MultiRewritePlan;
75}
76