Code Coverage
	Classes and Traits			Functions and Methods				Lines
Total							CRAP

1	<?php
2	/**
3	This file is part of the APP(ideas) database abstraction project (AiDb).
4	Copyright 2013, APPideas
5
6	AiDb is free software: you can redistribute it and/or modify
7	it under the terms of the GNU Lesser General Public License as published
8	by the Free Software Foundation, either version 3 of the License, or
9	(at your option) any later version.
10
11	AiDb is distributed in the hope that it will be useful,
12	but WITHOUT ANY WARRANTY; without even the implied warranty of
13	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14	GNU Lesser General Public License for more details.
15
16	You should have received a copy of the GNU Lesser General Public License
17	along with AiDb (in the 'resources' directory). If not, see
18	<http://www.gnu.org/licenses/>.
19	http://appideas.com/abstract-your-database-introduction
20	*/
21	/**
22	* The interface for DBMS implementors
23	*
24	* @package Ai_DatabaseAbstraction
25	*/
26	interface AiDb
27	{
28	/**
29	* Connect to the database and set the member connection resource
30	*
31	* @return void
32	* @since Version 20120328
33	* @author Version 20120328, costmo
34	*/
35	public function connect();
36
37	/**
38	* Perform a query of the database.
39	*
40	* This does not assume that strings have been escaped, so be sure to escape them.
41	*
42	* Use the PHP macros __FILE__ and __LINE__ for the 2nd and 3rd parameters.
43	*
44	* @return resource
45	* @since Version 20120328
46	* @author Version 20120328, costmo
47	* @param string $query The query to perform
48	* @param string $file The file making the query
49	* @param int $line The line number in the querying file
50	*/
51	public function query( $query, $file, $line );
52
53	/**
54	* Escape a string in a manner that the chosen DBMS can handle
55	*
56	* @return string
57	* @since Version 20120328
58	* @author Version 20120328, costmo
59	* @param string $string The string to escape
60	*/
61	public function escapeString( $string );
62
63	/**
64	* Returns any part of a query before a semi-colon
65	*
66	* If there is an attempt of an injection attack, or if your string input legitimately has semicolons,
67	* this is likely to cause truncated input.
68	*
69	* If your input may contain semicolons, be sure that you trust the source before allowing it to perfom
70	* a query.
71	*
72	* @return string
73	* @since Version 20120328
74	* @author Version 20120328, costmo
75	* @param string $string The string to de-inject
76	*/
77	public function blockInjection( $string );
78
79	/**
80	* Fetch a row form the database
81	*
82	* @return array
83	* @since Version 20120328
84	* @author Version 20120328, costmo
85	* @param resource $result The conenction resource returned by a query
86	*/
87	public function fetchRow( $result );
88
89	/**
90	* Fetch a row form the database and return it as an indexed array and an associative array with field names as indexes
91	*
92	* For consistency, returned keys are cast to lower case
93	*
94	* @return array
95	* @since Version 20120328
96	* @author Version 20120328, costmo
97	* @param resource $result The conenction resource returned by a query
98	*/
99	public function fetchArray( $result );
100
101	/**
102	* Get the name of a field at the given offset
103	*
104	* For consistency, returned values are cast to lower case
105	*
106	* @return string
107	* @since Version 20120328
108	* @author Version 20120328, costmo
109	* @param resource $result The conenction resource returned by a query
110	* @param int $columnOffset The offset of the requested column (0 is the first column)
111	*/
112	public function fieldName( $result, $columnOffset );
113
114	/**
115	* The number of rows returned by a query
116	*
117	* @return int
118	* @since Version 20120328
119	* @author Version 20120328, costmo
120	* @param resource $result The conenction resource returned by a query
121	*/
122	public function numRows( $result );
123
124	/**
125	* The number of fields returned by a query
126	*
127	* @return int
128	* @since Version 20120328
129	* @author Version 20120328, costmo
130	* @param resource $result The conenction resource returned by a query
131	*/
132	public function numFields( $result );
133
134	/**
135	* The type of field at the given offset
136	*
137	* The return type depends on the given database system. Each system returns different type information. Use $this->fieldSimpleType() for a more simplistic/portable data type representation
138	*
139	* @see $this::fieldSimpleType
140	* @return mixed
141	* @since Version 20120328
142	* @author Version 20120328, costmo
143	* @param resource $result The conenction resource returned by a query
144	* @param int $columnOffset The offset of the requested column (0 is the first column)
145	*/
146	public function fieldType( $result, $columnOffset );
147
148	/**
149	* A uniform type of field at the given offset.
150	*
151	* Returns a string that represents a simplified field type for consistency across DBMS'
152	*
153	* We don't check every field type. This has been written for the field types that APP(ideas) uses commonly. It will probably need modification to suit the needs of others.
154	*
155	* This globs a lot of different types together. You may need to make them more fine-grained
156	*
157	* @return string
158	* @since Version 20120328
159	* @author Version 20120328, costmo
160	* @param resource $result The conenction resource returned by a query
161	* @param int $columnOffset The offset of the requested column (0 is the first column)
162	*/
163	public function simpleFieldType( $result, $columnOffset );
164
165	/**
166	* Convert a database-formatted boolean value into something consistent with PHP
167	*
168	* @return bool
169	* @since Version 20120328
170	* @author Version 20120328, costmo
171	* @param string $booleanValue A boolean value retrieved from a database query
172	*/
173	public function fixBoolean( $booleanValue );
174
175	/**
176	* Fixes a boolean input value of any kind to one understood by the DBMS
177	*
178	* The data type returned depends on the DBMS being used
179	*
180	* @return mixed
181	* @since Version 20120328
182	* @author Version 20120328, costmo
183	* @param string $booleanValue A boolean value retrieved from a database query
184	*/
185	public function fixDbBoolean( $booleanValue );
186
187	/**
188	* Inserts a blank record into the requested table and returns the value of the surrogate key of the new record.
189	*
190	* This allows us to use a "modify" method for saving new data rather than separate "add" and "modify"
191	*
192	* If one of your "requiredFields" is a string, you must enclose it in apostrophes on input
193	*
194	* @return int
195	* @since Version 20120328
196	* @author Version 20120328, costmo
197	* @param string $tableName The name of the table into which we are inserting
198	* @param string $fieldName The name of the field into which we are inserting
199	* @param mixed $requiredFields An array of other fields and values that must not be null on a new record insert
200	*/
201	public function insertBlank( $tableName, $fieldName );
202
203	/**
204	* Begins a database transaction if supported by the DBMS
205	*
206	* @return void
207	* @since Version 20120328
208	* @author Version 20120328, costmo
209	* @param string $file The file making the query. Leave empty to report the DB connector file name.
210	* @param int $line The line number in the querying file. Leave empty to report the DB connector line number.
211	*/
212	public function beginTransaction( $file = false, $line = false );
213
214	/**
215	* Ends (commits) a database transaction if supported by the DBMS
216	*
217	* @return void
218	* @since Version 20120328
219	* @author Version 20120328, costmo
220	* @param string $file The file making the query. Leave empty to report the DB connector file name.
221	* @param int $line The line number in the querying file. Leave empty to report the DB connector line number.
222	*/
223	public function endTransaction( $file = false, $line = false );
224
225	/**
226	* Retrieves a value that can be inserted into the database as a date or timestamp indicating the current date and/or time
227	*
228	* @return string
229	* @since Version 20120328
230	* @author Version 20120328, costmo
231	* @param string $format The format of the string to return. One of 'database' 'epoch' or a PHP date() format. The default is 'database'
232	*/
233	public function getCurrentTimestamp( $format = 'database' );
234
235	/**
236	* Returns -1 if the versions table cannot be found, the current schema version number otherwise
237	*
238	* @return int
239	* @since Version 20120328
240	* @author Version 20120328, costmo
241	*/
242	public function getCurrentVersion();
243
244	/**
245	* Retrieves a list of all available files for possible upgrade/downgrade of the database schema.
246	*
247	* Will echo an error and exit if file validation does not pass
248	*
249	* @return array
250	* @since Version 20120328
251	* @author Version 20120328, costmo
252	* @param string $fromDir The input directory
253	*/
254	public function getUpgradeFiles( $fromDir );
255
256	/**
257	* Makes sure there are no skips in the version numbers
258	*
259	* @return bool
260	* @since Version 20120328
261	* @author Version 20120328, costmo
262	* @param array $files The retrieved files
263	*/
264	public function validateUpgradeFiles( $files );
265
266	/**
267	* Performs an upgrade to the latest version or downgrade a single version
268	*
269	* @return string
270	* @since Version 20120328
271	* @author Version 20120328, costmo
272	* @param int $fromVersion The user's current schema version
273	* @param string $direction "up" for an upgrade or "down" for a downgrade
274	*/
275	public function doUpgrade( $fromVersion, $direction );
276
277	/**
278	* Records a schema change in the database
279	*
280	* @return void
281	* @since Version 20120328
282	* @author Version 20120328, costmo
283	* @param string $action The action to perform. Either "add" or "delete"
284	* @param int $versionNumber The version number to record
285	*/
286	public function recordSchemaChange( $action, $versionNumber );
287