1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\db\tools;
15
16	/**
17	* Interface for a Database Tools for handling cross-db actions such as altering columns, etc.
18	*/
19	interface tools_interface
20	{
21	/**
22	* Handle passed database update array.
23	* Expected structure...
24	* Key being one of the following
25	*    drop_tables: Drop tables
26	*    add_tables: Add tables
27	*    change_columns: Column changes (only type, not name)
28	*    add_columns: Add columns to a table
29	*    drop_keys: Dropping keys
30	*    drop_columns: Removing/Dropping columns
31	*    add_primary_keys: adding primary keys
32	*    add_unique_index: adding an unique index
33	*    add_index: adding an index (can be column:index_size if you need to provide size)
34	*
35	* The values are in this format:
36	*        {TABLE NAME}        => array(
37	*            {COLUMN NAME}        => array({COLUMN TYPE}, {DEFAULT VALUE}, {OPTIONAL VARIABLES}),
38	*            {KEY/INDEX NAME}    => array({COLUMN NAMES}),
39	*        )
40	*
41	*
42	* @param array $schema_changes
43	*
44	* @return bool|string[]
45	*/
46	public function perform_schema_changes(array $schema_changes);
47
48	/**
49	* Gets a list of tables in the database.
50	*
51	* @return array        Array of table names  (all lower case)
52	*/
53	public function sql_list_tables(): array;
54
55	/**
56	* Check if table exists
57	*
58	* @param string $table_name The table name to check for
59	*
60	* @return bool True if table exists, else false
61	*/
62	public function sql_table_exists(string $table_name): bool;
63
64	/**
65	* Create SQL Table
66	*
67	* @param string $table_name The table name to create
68	* @param array  $table_data Array containing table data.
69	*
70	* @return bool|string[] True if the statements have been executed
71	*/
72	public function sql_create_table(string $table_name, array $table_data);
73
74	/**
75	* Drop Table
76	*
77	* @param string $table_name The table name to drop
78	*
79	* @return bool|string[]    True if the statements have been executed
80	*/
81	public function sql_table_drop(string $table_name);
82
83	/**
84	* Gets a list of columns of a table.
85	*
86	* @param string $table_name Table name
87	*
88	* @return array        Array of column names (all lower case)
89	*/
90	public function sql_list_columns(string $table_name): array;
91
92	/**
93	* Check whether a specified column exist in a table
94	*
95	* @param string $table_name  Table to check
96	* @param string $column_name Column to check
97	*
98	* @return bool        True if column exists, false otherwise
99	*/
100	public function sql_column_exists(string $table_name, string $column_name): bool;
101
102	/**
103	* Add new column
104	*
105	* @param string $table_name  Table to modify
106	* @param string $column_name Name of the column to add
107	* @param array  $column_data Column data
108	*
109	* @return bool|string[]    True if the statements have been executed
110	*/
111	public function sql_column_add(string $table_name, string $column_name, array $column_data);
112
113	/**
114	* Change column type (not name!)
115	*
116	* @param string $table_name  Table to modify
117	* @param string $column_name Name of the column to modify
118	* @param array  $column_data Column data
119	*
120	* @return bool|string[]    True if the statements have been executed
121	*/
122	public function sql_column_change(string $table_name, string $column_name, array $column_data);
123
124	/**
125	* Drop column
126	*
127	* @param string $table_name  Table to modify
128	* @param string $column_name Name of the column to drop
129	*
130	* @return bool|string[]    True if the statements have been executed
131	*/
132	public function sql_column_remove(string $table_name, string $column_name);
133
134	/**
135	* List all of the indices that belong to a table
136	*
137	* NOTE: does not list
138	* - UNIQUE indices
139	* - PRIMARY keys
140	*
141	* @param string $table_name Table to check
142	*
143	* @return array        Array with index names
144	*/
145	public function sql_list_index(string $table_name): array;
146
147	/**
148	* Check if a specified index exists in table. Does not return PRIMARY KEY and UNIQUE indexes.
149	*
150	* @param string $table_name Table to check the index at
151	* @param string $index_name The index name to check
152	*
153	* @return bool            True if index exists, else false
154	*/
155	public function sql_index_exists(string $table_name, string $index_name): bool;
156
157	/**
158	* Add index
159	*
160	* @param string       $table_name Table to modify
161	* @param string       $index_name Name of the index to create
162	* @param string|array $column     Either a string with a column name, or an array with columns
163	*
164	* @return bool|string[]    True if the statements have been executed
165	*/
166	public function sql_create_index(string $table_name, string $index_name, $column);
167
168	/**
169	* Rename index
170	*
171	* @param string $table_name     Table to modify
172	* @param string $index_name_old Name of the index to rename
173	* @param string $index_name_new New name of the index being renamed
174	*
175	* @return bool|string[]    True if the statements have been executed
176	*/
177	public function sql_rename_index(string $table_name, string $index_name_old, string $index_name_new);
178
179	/**
180	* Drop Index
181	*
182	* @param string $table_name Table to modify
183	* @param string $index_name Name of the index to delete
184	*
185	* @return bool|string[]    True if the statements have been executed
186	*/
187	public function sql_index_drop(string $table_name, string $index_name);
188
189	/**
190	* Check if a specified index exists in table.
191	*
192	* NOTE: Does not return normal and PRIMARY KEY indexes
193	*
194	* @param string $table_name Table to check the index at
195	* @param string $index_name The index name to check
196	*
197	* @return bool|string[] True if index exists, else false
198	*/
199	public function sql_unique_index_exists(string $table_name, string $index_name);
200
201	/**
202	* Add unique index
203	*
204	* @param string       $table_name Table to modify
205	* @param string       $index_name Name of the unique index to create
206	* @param string|array $column     Either a string with a column name, or an array with columns
207	*
208	* @return bool|string[]    True if the statements have been executed
209	*/
210	public function sql_create_unique_index(string $table_name, string $index_name, $column);
211
212	/**
213	* Add primary key
214	*
215	* @param string       $table_name Table to modify
216	* @param string|array $column     Either a string with a column name, or an array with columns
217	*
218	* @return bool|string[]    True if the statements have been executed
219	*/
220	public function sql_create_primary_key(string $table_name, $column);
221
222	/**
223	* Truncate the table
224	*
225	* @param string $table_name
226	* @return void
227	*/
228	public function sql_truncate_table(string $table_name): void;
229
230	/**
231	* Gets current Doctrine DBAL connection
232	*
233	* @return \Doctrine\DBAL\Connection
234	*/
235	public function get_connection(): \Doctrine\DBAL\Connection;
236
237	/**
238	* Adds prefix to a string if needed
239	*
240	* @param string    $name        Table name with tables prefix
241	* @param string    $prefix        Prefix to add
242	*
243	* @return string    Prefixed name
244	*/
245	public static function add_prefix(string $name, string $prefix): string;
246
247	/**
248	* Removes prefix from string if exists. If prefix is empty,
249	* the first part of the string ending with underscore will be removed.
250	*
251	* @param string    $name        String to remove the prefix from
252	* @param string    $prefix        Prefix to remove
253	*
254	* @return string    Prefixless string
255	*/
256	public static function remove_prefix(string $name, string $prefix = ''): string;
257
258	/**
259	* Sets table prefix
260	*
261	* @param string    $table_prefix    String to test vs prefix
262	*
263	* @return void
264	*/
265	public function set_table_prefix(string $table_prefix): void;
266	}