1	<?php
2
3	declare(strict_types=1);
4
5	namespace PeServer\Core\Database;
6
7	use PeServer\Core\Database\DatabaseRowResult;
8	use PeServer\Core\Database\IDatabaseImplementation;
9	use PeServer\Core\Throws\DatabaseException;
10	use PeServer\Core\Throws\ObjectDisposedException;
11	use PeServer\Core\Throws\SqlException;
12
13	/**
14	* `select` 系処理。
15	*
16	* 内容によっては実行処理がなされる。
17	*/
18	interface IDatabaseReader extends IDatabaseImplementation
19	{
20	#region function
21
22	/**
23	* 問い合わせを逐次実行。
24	*
25	* @template TFieldArray of FieldArrayAlias
26	* @param string $statement
27	* @phpstan-param literal-string $statement
28	* @param array<string|int,string|int|bool>|null $parameters
29	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
30	* @return DatabaseSequenceResult
31	* @phpstan-return DatabaseSequenceResult<TFieldArray>
32	* @throws SqlException 問い合わせ文の検証エラー
33	*/
34	public function fetch(string $statement, ?array $parameters = null): DatabaseSequenceResult;
35
36	/**
37	* 問い合わせを実行。
38	*
39	* @template TFieldArray of FieldArrayAlias
40	* @param string $statement
41	* @phpstan-param literal-string $statement
42	* @param array<string|int,string|int|bool>|null $parameters
43	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
44	* @return DatabaseTableResult
45	* @phpstan-return DatabaseTableResult<TFieldArray>
46	* @throws DatabaseException
47	* @throws SqlException 問い合わせ文の検証エラー
48	*/
49	public function query(string $statement, ?array $parameters = null): DatabaseTableResult;
50
51	/**
52	* 問い合わせの最初のデータを取得。
53	*
54	* @template TFieldArray of FieldArrayAlias
55	* @param string $statement
56	* @phpstan-param literal-string $statement
57	* @param array<string|int,string|int|bool>|null $parameters
58	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
59	* @return DatabaseRowResult
60	* @phpstan-return DatabaseRowResult<TFieldArray>
61	* @throws DatabaseException
62	* @throws SqlException 問い合わせ文の検証エラー
63	*/
64	public function queryFirst(string $statement, ?array $parameters = null): DatabaseRowResult;
65
66	/**
67	* 問い合わせの最初のデータを取得。存在しない場合に `null` を返す。
68	*
69	* @template TFieldArray of FieldArrayAlias
70	* @param string $statement
71	* @phpstan-param literal-string $statement
72	* @param array<string|int,string|int|bool>|null $parameters
73	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
74	* @return DatabaseRowResult|null
75	* @phpstan-return DatabaseRowResult<TFieldArray>|null
76	* @throws DatabaseException
77	* @throws SqlException 問い合わせ文の検証エラー
78	*/
79	public function queryFirstOrNull(string $statement, ?array $parameters = null): ?DatabaseRowResult;
80
81	/**
82	* 1件だけの問い合わせを実行。
83	*
84	* @template TFieldArray of FieldArrayAlias
85	* @param string $statement
86	* @phpstan-param literal-string $statement
87	* @param array<string|int,string|int|bool>|null $parameters
88	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
89	* @return DatabaseRowResult
90	* @phpstan-return DatabaseRowResult<TFieldArray>
91	* @throws DatabaseException
92	* @throws SqlException 問い合わせ文の検証エラー
93	*/
94	public function querySingle(string $statement, ?array $parameters = null): DatabaseRowResult;
95
96	/**
97	* 1件だけの問い合わせを実行。存在しない場合に `null` を返す
98	*
99	* @template TFieldArray of FieldArrayAlias
100	* @param string $statement
101	* @phpstan-param literal-string $statement
102	* @param array<string|int,string|int|bool>|null $parameters
103	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
104	* @return DatabaseRowResult|null
105	* @phpstan-return DatabaseRowResult<TFieldArray>|null
106	* @throws DatabaseException
107	* @throws SqlException 問い合わせ文の検証エラー
108	*/
109	public function querySingleOrNull(string $statement, ?array $parameters = null): ?DatabaseRowResult;
110
111	/**
112	* 並び順問い合わせ文を強制。
113	*
114	* 単純な文字列処理のため無理な時は無理。
115	*
116	* @template TFieldArray of FieldArrayAlias
117	* @param string $statement
118	* @phpstan-param literal-string $statement
119	* @param array<string|int,string|int|bool>|null $parameters
120	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
121	* @return DatabaseTableResult
122	* @phpstan-return DatabaseTableResult<TFieldArray>
123	* @throws DatabaseException
124	* @throws SqlException 問い合わせ文の検証エラー
125	*/
126	public function selectOrdered(string $statement, ?array $parameters = null): DatabaseTableResult;
127
128	/**
129	* 単一 COUNT 関数問い合わせ文を強制。
130	*
131	* 単純な文字列処理のため無理な時は無理。
132	*
133	* @param string $statement
134	* @phpstan-param literal-string $statement
135	* @param array<string|int,string|int|bool>|null $parameters
136	* @phpstan-param array<array-key,DatabaseBindValueAlias>|null $parameters
137	* @return int
138	* @phpstan-return non-negative-int
139	* @throws DatabaseException
140	* @throws SqlException 問い合わせ文の検証エラー
141	*/
142	public function selectSingleCount(string $statement, ?array $parameters = null): int;
143
144	#endregion
145	}