1 | <?php |
---|
2 | |
---|
3 | /** |
---|
4 | * @file |
---|
5 | * Wrapper for database interface code. |
---|
6 | */ |
---|
7 | |
---|
8 | /** |
---|
9 | * A hash value to check when outputting database errors, md5('DB_ERROR'). |
---|
10 | * |
---|
11 | * @see drupal_error_handler() |
---|
12 | */ |
---|
13 | define('DB_ERROR', 'a515ac9c2796ca0e23adbe92c68fc9fc'); |
---|
14 | |
---|
15 | /** |
---|
16 | * @defgroup database Database abstraction layer |
---|
17 | * @{ |
---|
18 | * Allow the use of different database servers using the same code base. |
---|
19 | * |
---|
20 | * Drupal provides a slim database abstraction layer to provide developers with |
---|
21 | * the ability to support multiple database servers easily. The intent of this |
---|
22 | * layer is to preserve the syntax and power of SQL as much as possible, while |
---|
23 | * letting Drupal control the pieces of queries that need to be written |
---|
24 | * differently for different servers and provide basic security checks. |
---|
25 | * |
---|
26 | * Most Drupal database queries are performed by a call to db_query() or |
---|
27 | * db_query_range(). Module authors should also consider using pager_query() for |
---|
28 | * queries that return results that need to be presented on multiple pages, and |
---|
29 | * tablesort_sql() for generating appropriate queries for sortable tables. |
---|
30 | * |
---|
31 | * For example, one might wish to return a list of the most recent 10 nodes |
---|
32 | * authored by a given user. Instead of directly issuing the SQL query |
---|
33 | * @code |
---|
34 | * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10; |
---|
35 | * @endcode |
---|
36 | * one would instead call the Drupal functions: |
---|
37 | * @code |
---|
38 | * $result = db_query_range('SELECT n.nid, n.title, n.created |
---|
39 | * FROM {node} n WHERE n.uid = %d', $uid, 0, 10); |
---|
40 | * while ($node = db_fetch_object($result)) { |
---|
41 | * // Perform operations on $node->body, etc. here. |
---|
42 | * } |
---|
43 | * @endcode |
---|
44 | * Curly braces are used around "node" to provide table prefixing via |
---|
45 | * db_prefix_tables(). The explicit use of a user ID is pulled out into an |
---|
46 | * argument passed to db_query() so that SQL injection attacks from user input |
---|
47 | * can be caught and nullified. The LIMIT syntax varies between database servers, |
---|
48 | * so that is abstracted into db_query_range() arguments. Finally, note the |
---|
49 | * common pattern of iterating over the result set using db_fetch_object(). |
---|
50 | */ |
---|
51 | |
---|
52 | /** |
---|
53 | * Perform an SQL query and return success or failure. |
---|
54 | * |
---|
55 | * @param $sql |
---|
56 | * A string containing a complete SQL query. %-substitution |
---|
57 | * parameters are not supported. |
---|
58 | * @return |
---|
59 | * An array containing the keys: |
---|
60 | * success: a boolean indicating whether the query succeeded |
---|
61 | * query: the SQL query executed, passed through check_plain() |
---|
62 | */ |
---|
63 | function update_sql($sql) { |
---|
64 | $result = db_query($sql, true); |
---|
65 | return array('success' => $result !== FALSE, 'query' => check_plain($sql)); |
---|
66 | } |
---|
67 | |
---|
68 | /** |
---|
69 | * Append a database prefix to all tables in a query. |
---|
70 | * |
---|
71 | * Queries sent to Drupal should wrap all table names in curly brackets. This |
---|
72 | * function searches for this syntax and adds Drupal's table prefix to all |
---|
73 | * tables, allowing Drupal to coexist with other systems in the same database if |
---|
74 | * necessary. |
---|
75 | * |
---|
76 | * @param $sql |
---|
77 | * A string containing a partial or entire SQL query. |
---|
78 | * @return |
---|
79 | * The properly-prefixed string. |
---|
80 | */ |
---|
81 | function db_prefix_tables($sql) { |
---|
82 | global $db_prefix; |
---|
83 | |
---|
84 | if (is_array($db_prefix)) { |
---|
85 | if (array_key_exists('default', $db_prefix)) { |
---|
86 | $tmp = $db_prefix; |
---|
87 | unset($tmp['default']); |
---|
88 | foreach ($tmp as $key => $val) { |
---|
89 | $sql = strtr($sql, array('{'. $key .'}' => $val . $key)); |
---|
90 | } |
---|
91 | return strtr($sql, array('{' => $db_prefix['default'], '}' => '')); |
---|
92 | } |
---|
93 | else { |
---|
94 | foreach ($db_prefix as $key => $val) { |
---|
95 | $sql = strtr($sql, array('{'. $key .'}' => $val . $key)); |
---|
96 | } |
---|
97 | return strtr($sql, array('{' => '', '}' => '')); |
---|
98 | } |
---|
99 | } |
---|
100 | else { |
---|
101 | return strtr($sql, array('{' => $db_prefix, '}' => '')); |
---|
102 | } |
---|
103 | } |
---|
104 | |
---|
105 | /** |
---|
106 | * Activate a database for future queries. |
---|
107 | * |
---|
108 | * If it is necessary to use external databases in a project, this function can |
---|
109 | * be used to change where database queries are sent. If the database has not |
---|
110 | * yet been used, it is initialized using the URL specified for that name in |
---|
111 | * Drupal's configuration file. If this name is not defined, a duplicate of the |
---|
112 | * default connection is made instead. |
---|
113 | * |
---|
114 | * Be sure to change the connection back to the default when done with custom |
---|
115 | * code. |
---|
116 | * |
---|
117 | * @param $name |
---|
118 | * The key in the $db_url global variable from settings.php. If omitted, the |
---|
119 | * default connection will be made active. |
---|
120 | * |
---|
121 | * @return |
---|
122 | * The name of the previously active database, or FALSE if none was found. |
---|
123 | */ |
---|
124 | function db_set_active($name = 'default') { |
---|
125 | global $db_url, $db_type, $active_db; |
---|
126 | static $db_conns, $active_name = FALSE; |
---|
127 | |
---|
128 | if (empty($db_url)) { |
---|
129 | include_once 'includes/install.inc'; |
---|
130 | install_goto('install.php'); |
---|
131 | } |
---|
132 | |
---|
133 | if (!isset($db_conns[$name])) { |
---|
134 | // Initiate a new connection, using the named DB URL specified. |
---|
135 | if (is_array($db_url)) { |
---|
136 | $connect_url = array_key_exists($name, $db_url) ? $db_url[$name] : $db_url['default']; |
---|
137 | } |
---|
138 | else { |
---|
139 | $connect_url = $db_url; |
---|
140 | } |
---|
141 | |
---|
142 | $db_type = substr($connect_url, 0, strpos($connect_url, '://')); |
---|
143 | $handler = "./includes/database.$db_type.inc"; |
---|
144 | |
---|
145 | if (is_file($handler)) { |
---|
146 | include_once $handler; |
---|
147 | } |
---|
148 | else { |
---|
149 | _db_error_page("The database type '". $db_type ."' is unsupported. Please use either 'mysql' or 'mysqli' for MySQL, or 'pgsql' for PostgreSQL databases."); |
---|
150 | } |
---|
151 | |
---|
152 | $db_conns[$name] = db_connect($connect_url); |
---|
153 | } |
---|
154 | |
---|
155 | $previous_name = $active_name; |
---|
156 | // Set the active connection. |
---|
157 | $active_name = $name; |
---|
158 | $active_db = $db_conns[$name]; |
---|
159 | |
---|
160 | return $previous_name; |
---|
161 | } |
---|
162 | |
---|
163 | /** |
---|
164 | * Helper function to show fatal database errors. |
---|
165 | * |
---|
166 | * Prints a themed maintenance page with the 'Site off-line' text, |
---|
167 | * adding the provided error message in the case of 'display_errors' |
---|
168 | * set to on. Ends the page request; no return. |
---|
169 | * |
---|
170 | * @param $error |
---|
171 | * The error message to be appended if 'display_errors' is on. |
---|
172 | */ |
---|
173 | function _db_error_page($error = '') { |
---|
174 | global $db_type; |
---|
175 | drupal_init_language(); |
---|
176 | drupal_maintenance_theme(); |
---|
177 | drupal_set_header($_SERVER['SERVER_PROTOCOL'] .' 503 Service Unavailable'); |
---|
178 | drupal_set_title('Site off-line'); |
---|
179 | |
---|
180 | $message = '<p>The site is currently not available due to technical problems. Please try again later. Thank you for your understanding.</p>'; |
---|
181 | $message .= '<hr /><p><small>If you are the maintainer of this site, please check your database settings in the <code>settings.php</code> file and ensure that your hosting provider\'s database server is running. For more help, see the <a href="http://drupal.org/node/258">handbook</a>, or contact your hosting provider.</small></p>'; |
---|
182 | |
---|
183 | if ($error && ini_get('display_errors')) { |
---|
184 | $message .= '<p><small>The '. theme('placeholder', $db_type) .' error was: '. theme('placeholder', $error) .'.</small></p>'; |
---|
185 | } |
---|
186 | |
---|
187 | print theme('maintenance_page', $message); |
---|
188 | exit; |
---|
189 | } |
---|
190 | |
---|
191 | /** |
---|
192 | * Returns a boolean depending on the availability of the database. |
---|
193 | */ |
---|
194 | function db_is_active() { |
---|
195 | global $active_db; |
---|
196 | return !empty($active_db); |
---|
197 | } |
---|
198 | |
---|
199 | /** |
---|
200 | * Helper function for db_query(). |
---|
201 | */ |
---|
202 | function _db_query_callback($match, $init = FALSE) { |
---|
203 | static $args = NULL; |
---|
204 | if ($init) { |
---|
205 | $args = $match; |
---|
206 | return; |
---|
207 | } |
---|
208 | |
---|
209 | switch ($match[1]) { |
---|
210 | case '%d': // We must use type casting to int to convert FALSE/NULL/(TRUE?) |
---|
211 | $value = array_shift($args); |
---|
212 | // Do we need special bigint handling? |
---|
213 | if ($value > PHP_INT_MAX) { |
---|
214 | $precision = ini_get('precision'); |
---|
215 | @ini_set('precision', 16); |
---|
216 | $value = sprintf('%.0f', $value); |
---|
217 | @ini_set('precision', $precision); |
---|
218 | } |
---|
219 | else { |
---|
220 | $value = (int) $value; |
---|
221 | } |
---|
222 | // We don't need db_escape_string as numbers are db-safe. |
---|
223 | return $value; |
---|
224 | case '%s': |
---|
225 | return db_escape_string(array_shift($args)); |
---|
226 | case '%n': |
---|
227 | // Numeric values have arbitrary precision, so can't be treated as float. |
---|
228 | // is_numeric() allows hex values (0xFF), but they are not valid. |
---|
229 | $value = trim(array_shift($args)); |
---|
230 | return is_numeric($value) && !preg_match('/x/i', $value) ? $value : '0'; |
---|
231 | case '%%': |
---|
232 | return '%'; |
---|
233 | case '%f': |
---|
234 | return (float) array_shift($args); |
---|
235 | case '%b': // binary data |
---|
236 | return db_encode_blob(array_shift($args)); |
---|
237 | } |
---|
238 | } |
---|
239 | |
---|
240 | /** |
---|
241 | * Generate placeholders for an array of query arguments of a single type. |
---|
242 | * |
---|
243 | * Given a Schema API field type, return correct %-placeholders to |
---|
244 | * embed in a query |
---|
245 | * |
---|
246 | * @param $arguments |
---|
247 | * An array with at least one element. |
---|
248 | * @param $type |
---|
249 | * The Schema API type of a field (e.g. 'int', 'text', or 'varchar'). |
---|
250 | */ |
---|
251 | function db_placeholders($arguments, $type = 'int') { |
---|
252 | $placeholder = db_type_placeholder($type); |
---|
253 | return implode(',', array_fill(0, count($arguments), $placeholder)); |
---|
254 | } |
---|
255 | |
---|
256 | /** |
---|
257 | * Indicates the place holders that should be replaced in _db_query_callback(). |
---|
258 | */ |
---|
259 | define('DB_QUERY_REGEXP', '/(%d|%s|%%|%f|%b|%n)/'); |
---|
260 | |
---|
261 | /** |
---|
262 | * Helper function for db_rewrite_sql. |
---|
263 | * |
---|
264 | * Collects JOIN and WHERE statements via hook_db_rewrite_sql() |
---|
265 | * Decides whether to select primary_key or DISTINCT(primary_key) |
---|
266 | * |
---|
267 | * @param $query |
---|
268 | * Query to be rewritten. |
---|
269 | * @param $primary_table |
---|
270 | * Name or alias of the table which has the primary key field for this query. |
---|
271 | * Typical table names would be: {blocks}, {comments}, {forum}, {node}, |
---|
272 | * {menu}, {term_data} or {vocabulary}. However, in most cases the usual |
---|
273 | * table alias (b, c, f, n, m, t or v) is used instead of the table name. |
---|
274 | * @param $primary_field |
---|
275 | * Name of the primary field. |
---|
276 | * @param $args |
---|
277 | * Array of additional arguments. |
---|
278 | * @return |
---|
279 | * An array: join statements, where statements, field or DISTINCT(field). |
---|
280 | */ |
---|
281 | function _db_rewrite_sql($query = '', $primary_table = 'n', $primary_field = 'nid', $args = array()) { |
---|
282 | $where = array(); |
---|
283 | $join = array(); |
---|
284 | $distinct = FALSE; |
---|
285 | foreach (module_implements('db_rewrite_sql') as $module) { |
---|
286 | $result = module_invoke($module, 'db_rewrite_sql', $query, $primary_table, $primary_field, $args); |
---|
287 | if (isset($result) && is_array($result)) { |
---|
288 | if (isset($result['where'])) { |
---|
289 | $where[] = $result['where']; |
---|
290 | } |
---|
291 | if (isset($result['join'])) { |
---|
292 | $join[] = $result['join']; |
---|
293 | } |
---|
294 | if (isset($result['distinct']) && $result['distinct']) { |
---|
295 | $distinct = TRUE; |
---|
296 | } |
---|
297 | } |
---|
298 | elseif (isset($result)) { |
---|
299 | $where[] = $result; |
---|
300 | } |
---|
301 | } |
---|
302 | |
---|
303 | $where = empty($where) ? '' : '('. implode(') AND (', $where) .')'; |
---|
304 | $join = empty($join) ? '' : implode(' ', $join); |
---|
305 | |
---|
306 | return array($join, $where, $distinct); |
---|
307 | } |
---|
308 | |
---|
309 | /** |
---|
310 | * Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not |
---|
311 | * use FROM table1, table2 syntax, use JOIN instead. |
---|
312 | * |
---|
313 | * @param $query |
---|
314 | * Query to be rewritten. |
---|
315 | * @param $primary_table |
---|
316 | * Name or alias of the table which has the primary key field for this query. |
---|
317 | * Typical table names would be: {blocks}, {comments}, {forum}, {node}, |
---|
318 | * {menu}, {term_data} or {vocabulary}. However, it is more common to use the |
---|
319 | * the usual table aliases: b, c, f, n, m, t or v. |
---|
320 | * @param $primary_field |
---|
321 | * Name of the primary field. |
---|
322 | * @param $args |
---|
323 | * An array of arguments, passed to the implementations of hook_db_rewrite_sql. |
---|
324 | * @return |
---|
325 | * The original query with JOIN and WHERE statements inserted from |
---|
326 | * hook_db_rewrite_sql implementations. nid is rewritten if needed. |
---|
327 | */ |
---|
328 | function db_rewrite_sql($query, $primary_table = 'n', $primary_field = 'nid', $args = array()) { |
---|
329 | list($join, $where, $distinct) = _db_rewrite_sql($query, $primary_table, $primary_field, $args); |
---|
330 | |
---|
331 | if ($distinct) { |
---|
332 | $query = db_distinct_field($primary_table, $primary_field, $query); |
---|
333 | } |
---|
334 | |
---|
335 | if (!empty($where) || !empty($join)) { |
---|
336 | $pattern = '{ |
---|
337 | # Beginning of the string |
---|
338 | ^ |
---|
339 | ((?P<anonymous_view> |
---|
340 | # Everything within this set of parentheses is named "anonymous view" |
---|
341 | (?: |
---|
342 | [^()]++ # anything not parentheses |
---|
343 | | |
---|
344 | \( (?P>anonymous_view) \) # an open parenthesis, more "anonymous view" and finally a close parenthesis. |
---|
345 | )* |
---|
346 | )[^()]+WHERE) |
---|
347 | }x'; |
---|
348 | preg_match($pattern, $query, $matches); |
---|
349 | if (!$where) { |
---|
350 | $where = '1 = 1'; |
---|
351 | } |
---|
352 | if ($matches) { |
---|
353 | $n = strlen($matches[1]); |
---|
354 | $second_part = substr($query, $n); |
---|
355 | $first_part = substr($matches[1], 0, $n - 5) ." $join WHERE $where AND ( "; |
---|
356 | // PHP 4 does not support strrpos for strings. We emulate it. |
---|
357 | $haystack_reverse = strrev($second_part); |
---|
358 | } |
---|
359 | else { |
---|
360 | $haystack_reverse = strrev($query); |
---|
361 | } |
---|
362 | // No need to use strrev on the needle, we supply GROUP, ORDER, LIMIT |
---|
363 | // reversed. |
---|
364 | foreach (array('PUORG', 'REDRO', 'TIMIL') as $needle_reverse) { |
---|
365 | $pos = strpos($haystack_reverse, $needle_reverse); |
---|
366 | if ($pos !== FALSE) { |
---|
367 | // All needles are five characters long. |
---|
368 | $pos += 5; |
---|
369 | break; |
---|
370 | } |
---|
371 | } |
---|
372 | if ($matches) { |
---|
373 | if ($pos === FALSE) { |
---|
374 | $query = $first_part . $second_part .')'; |
---|
375 | } |
---|
376 | else { |
---|
377 | $query = $first_part . substr($second_part, 0, -$pos) .')'. substr($second_part, -$pos); |
---|
378 | } |
---|
379 | } |
---|
380 | elseif ($pos === FALSE) { |
---|
381 | $query .= " $join WHERE $where"; |
---|
382 | } |
---|
383 | else { |
---|
384 | $query = substr($query, 0, -$pos) . " $join WHERE $where " . substr($query, -$pos); |
---|
385 | } |
---|
386 | } |
---|
387 | |
---|
388 | return $query; |
---|
389 | } |
---|
390 | |
---|
391 | /** |
---|
392 | * Adds the DISTINCT flag to the supplied query and returns the altered query. |
---|
393 | * |
---|
394 | * The supplied query should not contain a DISTINCT flag. This will not, and |
---|
395 | * never did guarantee that you will obtain distinct values of $table.$field. |
---|
396 | * |
---|
397 | * @param $table |
---|
398 | * Unused. Kept to retain API compatibility. |
---|
399 | * @param $field |
---|
400 | * Unused. Kept to retain API compatibility. |
---|
401 | * @param $query |
---|
402 | * Query to which the DISTINCT flag should be applied. |
---|
403 | * |
---|
404 | * @return |
---|
405 | * SQL query with the DISTINCT flag set. |
---|
406 | */ |
---|
407 | function db_distinct_field($table, $field, $query) { |
---|
408 | $matches = array(); |
---|
409 | if (!preg_match('/^SELECT\s*DISTINCT/i', $query, $matches)) { |
---|
410 | // Only add distinct to the outer SELECT to avoid messing up subqueries. |
---|
411 | $query = preg_replace('/^SELECT/i', 'SELECT DISTINCT', $query); |
---|
412 | } |
---|
413 | |
---|
414 | return $query; |
---|
415 | } |
---|
416 | |
---|
417 | /** |
---|
418 | * Restrict a dynamic table, column or constraint name to safe characters. |
---|
419 | * |
---|
420 | * Only keeps alphanumeric and underscores. |
---|
421 | */ |
---|
422 | function db_escape_table($string) { |
---|
423 | return preg_replace('/[^A-Za-z0-9_]+/', '', $string); |
---|
424 | } |
---|
425 | |
---|
426 | /** |
---|
427 | * @} End of "defgroup database". |
---|
428 | */ |
---|
429 | |
---|
430 | /** |
---|
431 | * @defgroup schemaapi Schema API |
---|
432 | * @{ |
---|
433 | * |
---|
434 | * A Drupal schema definition is an array structure representing one or |
---|
435 | * more tables and their related keys and indexes. A schema is defined by |
---|
436 | * hook_schema(), which usually lives in a modulename.install file. |
---|
437 | * |
---|
438 | * By implementing hook_schema() and specifying the tables your module |
---|
439 | * declares, you can easily create and drop these tables on all |
---|
440 | * supported database engines. You don't have to deal with the |
---|
441 | * different SQL dialects for table creation and alteration of the |
---|
442 | * supported database engines. |
---|
443 | * |
---|
444 | * hook_schema() should return an array with a key for each table that |
---|
445 | * the module defines. |
---|
446 | * |
---|
447 | * The following keys are defined: |
---|
448 | * |
---|
449 | * - 'description': A string describing this table and its purpose. |
---|
450 | * References to other tables should be enclosed in |
---|
451 | * curly-brackets. For example, the node_revisions table |
---|
452 | * description field might contain "Stores per-revision title and |
---|
453 | * body data for each {node}." |
---|
454 | * - 'fields': An associative array ('fieldname' => specification) |
---|
455 | * that describes the table's database columns. The specification |
---|
456 | * is also an array. The following specification parameters are defined: |
---|
457 | * - 'description': A string describing this field and its purpose. |
---|
458 | * References to other tables should be enclosed in |
---|
459 | * curly-brackets. For example, the node table vid field |
---|
460 | * description might contain "Always holds the largest (most |
---|
461 | * recent) {node_revisions}.vid value for this nid." |
---|
462 | * - 'type': The generic datatype: 'varchar', 'int', 'serial' |
---|
463 | * 'float', 'numeric', 'text', 'blob' or 'datetime'. Most types |
---|
464 | * just map to the according database engine specific |
---|
465 | * datatypes. Use 'serial' for auto incrementing fields. This |
---|
466 | * will expand to 'int auto_increment' on mysql. |
---|
467 | * - 'serialize': A boolean indicating whether the field will be stored |
---|
468 | as a serialized string. |
---|
469 | * - 'size': The data size: 'tiny', 'small', 'medium', 'normal', |
---|
470 | * 'big'. This is a hint about the largest value the field will |
---|
471 | * store and determines which of the database engine specific |
---|
472 | * datatypes will be used (e.g. on MySQL, TINYINT vs. INT vs. BIGINT). |
---|
473 | * 'normal', the default, selects the base type (e.g. on MySQL, |
---|
474 | * INT, VARCHAR, BLOB, etc.). |
---|
475 | * Not all sizes are available for all data types. See |
---|
476 | * db_type_map() for possible combinations. |
---|
477 | * - 'not null': If true, no NULL values will be allowed in this |
---|
478 | * database column. Defaults to false. |
---|
479 | * - 'default': The field's default value. The PHP type of the |
---|
480 | * value matters: '', '0', and 0 are all different. If you |
---|
481 | * specify '0' as the default value for a type 'int' field it |
---|
482 | * will not work because '0' is a string containing the |
---|
483 | * character "zero", not an integer. |
---|
484 | * - 'length': The maximal length of a type 'char', 'varchar' or 'text' |
---|
485 | * field. Ignored for other field types. |
---|
486 | * - 'unsigned': A boolean indicating whether a type 'int', 'float' |
---|
487 | * and 'numeric' only is signed or unsigned. Defaults to |
---|
488 | * FALSE. Ignored for other field types. |
---|
489 | * - 'precision', 'scale': For type 'numeric' fields, indicates |
---|
490 | * the precision (total number of significant digits) and scale |
---|
491 | * (decimal digits right of the decimal point). Both values are |
---|
492 | * mandatory. Ignored for other field types. |
---|
493 | * All parameters apart from 'type' are optional except that type |
---|
494 | * 'numeric' columns must specify 'precision' and 'scale'. |
---|
495 | * - 'primary key': An array of one or more key column specifiers (see below) |
---|
496 | * that form the primary key. |
---|
497 | * - 'unique keys': An associative array of unique keys ('keyname' => |
---|
498 | * specification). Each specification is an array of one or more |
---|
499 | * key column specifiers (see below) that form a unique key on the table. |
---|
500 | * - 'indexes': An associative array of indexes ('indexame' => |
---|
501 | * specification). Each specification is an array of one or more |
---|
502 | * key column specifiers (see below) that form an index on the |
---|
503 | * table. |
---|
504 | * |
---|
505 | * A key column specifier is either a string naming a column or an |
---|
506 | * array of two elements, column name and length, specifying a prefix |
---|
507 | * of the named column. |
---|
508 | * |
---|
509 | * As an example, here is a SUBSET of the schema definition for |
---|
510 | * Drupal's 'node' table. It show four fields (nid, vid, type, and |
---|
511 | * title), the primary key on field 'nid', a unique key named 'vid' on |
---|
512 | * field 'vid', and two indexes, one named 'nid' on field 'nid' and |
---|
513 | * one named 'node_title_type' on the field 'title' and the first four |
---|
514 | * bytes of the field 'type': |
---|
515 | * |
---|
516 | * @code |
---|
517 | * $schema['node'] = array( |
---|
518 | * 'fields' => array( |
---|
519 | * 'nid' => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE), |
---|
520 | * 'vid' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0), |
---|
521 | * 'type' => array('type' => 'varchar', 'length' => 32, 'not null' => TRUE, 'default' => ''), |
---|
522 | * 'title' => array('type' => 'varchar', 'length' => 128, 'not null' => TRUE, 'default' => ''), |
---|
523 | * ), |
---|
524 | * 'primary key' => array('nid'), |
---|
525 | * 'unique keys' => array( |
---|
526 | * 'vid' => array('vid') |
---|
527 | * ), |
---|
528 | * 'indexes' => array( |
---|
529 | * 'nid' => array('nid'), |
---|
530 | * 'node_title_type' => array('title', array('type', 4)), |
---|
531 | * ), |
---|
532 | * ); |
---|
533 | * @endcode |
---|
534 | * |
---|
535 | * @see drupal_install_schema() |
---|
536 | */ |
---|
537 | |
---|
538 | /** |
---|
539 | * Create a new table from a Drupal table definition. |
---|
540 | * |
---|
541 | * @param $ret |
---|
542 | * Array to which query results will be added. |
---|
543 | * @param $name |
---|
544 | * The name of the table to create. |
---|
545 | * @param $table |
---|
546 | * A Schema API table definition array. |
---|
547 | */ |
---|
548 | function db_create_table(&$ret, $name, $table) { |
---|
549 | $statements = db_create_table_sql($name, $table); |
---|
550 | foreach ($statements as $statement) { |
---|
551 | $ret[] = update_sql($statement); |
---|
552 | } |
---|
553 | } |
---|
554 | |
---|
555 | /** |
---|
556 | * Return an array of field names from an array of key/index column specifiers. |
---|
557 | * |
---|
558 | * This is usually an identity function but if a key/index uses a column prefix |
---|
559 | * specification, this function extracts just the name. |
---|
560 | * |
---|
561 | * @param $fields |
---|
562 | * An array of key/index column specifiers. |
---|
563 | * @return |
---|
564 | * An array of field names. |
---|
565 | */ |
---|
566 | function db_field_names($fields) { |
---|
567 | $ret = array(); |
---|
568 | foreach ($fields as $field) { |
---|
569 | if (is_array($field)) { |
---|
570 | $ret[] = $field[0]; |
---|
571 | } |
---|
572 | else { |
---|
573 | $ret[] = $field; |
---|
574 | } |
---|
575 | } |
---|
576 | return $ret; |
---|
577 | } |
---|
578 | |
---|
579 | /** |
---|
580 | * Given a Schema API field type, return the correct %-placeholder. |
---|
581 | * |
---|
582 | * Embed the placeholder in a query to be passed to db_query and and pass as an |
---|
583 | * argument to db_query a value of the specified type. |
---|
584 | * |
---|
585 | * @param $type |
---|
586 | * The Schema API type of a field. |
---|
587 | * @return |
---|
588 | * The placeholder string to embed in a query for that type. |
---|
589 | */ |
---|
590 | function db_type_placeholder($type) { |
---|
591 | switch ($type) { |
---|
592 | case 'varchar': |
---|
593 | case 'char': |
---|
594 | case 'text': |
---|
595 | case 'datetime': |
---|
596 | return "'%s'"; |
---|
597 | |
---|
598 | case 'numeric': |
---|
599 | // Numeric values are arbitrary precision numbers. Syntacically, numerics |
---|
600 | // should be specified directly in SQL. However, without single quotes |
---|
601 | // the %s placeholder does not protect against non-numeric characters such |
---|
602 | // as spaces which would expose us to SQL injection. |
---|
603 | return '%n'; |
---|
604 | |
---|
605 | case 'serial': |
---|
606 | case 'int': |
---|
607 | return '%d'; |
---|
608 | |
---|
609 | case 'float': |
---|
610 | return '%f'; |
---|
611 | |
---|
612 | case 'blob': |
---|
613 | return '%b'; |
---|
614 | } |
---|
615 | |
---|
616 | // There is no safe value to return here, so return something that |
---|
617 | // will cause the query to fail. |
---|
618 | return 'unsupported type '. $type .'for db_type_placeholder'; |
---|
619 | } |
---|
620 | |
---|
621 | /** |
---|
622 | * @} End of "defgroup schemaapi". |
---|
623 | */ |
---|