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	* Drop Index
170	*
171	* @param string $table_name Table to modify
172	* @param string $index_name Name of the index to delete
173	*
174	* @return bool|string[]    True if the statements have been executed
175	*/
176	public function sql_index_drop(string $table_name, string $index_name);
177
178	/**
179	* Check if a specified index exists in table.
180	*
181	* NOTE: Does not return normal and PRIMARY KEY indexes
182	*
183	* @param string $table_name Table to check the index at
184	* @param string $index_name The index name to check
185	*
186	* @return bool|string[] True if index exists, else false
187	*/
188	public function sql_unique_index_exists(string $table_name, string $index_name);
189
190	/**
191	* Add unique index
192	*
193	* @param string       $table_name Table to modify
194	* @param string       $index_name Name of the unique index to create
195	* @param string|array $column     Either a string with a column name, or an array with columns
196	*
197	* @return bool|string[]    True if the statements have been executed
198	*/
199	public function sql_create_unique_index(string $table_name, string $index_name, $column);
200
201	/**
202	* Add primary key
203	*
204	* @param string       $table_name Table to modify
205	* @param string|array $column     Either a string with a column name, or an array with columns
206	*
207	* @return bool|string[]    True if the statements have been executed
208	*/
209	public function sql_create_primary_key(string $table_name, $column);
210
211	/**
212	* Truncate the table
213	*
214	* @param string $table_name
215	* @return void
216	*/
217	public function sql_truncate_table(string $table_name): void;
218	}