summaryrefslogtreecommitdiffstats
path: root/data.module
blob: 4be283022b25ff3c6478cc81cd4e3274bb6dc38c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<?php
// $Id$
/**
 * @file
 * Hooks and API functions for data module.
 */

// Constant designating an undefined export state.
// Used in absence of EXPORT_IN_CODE, EXPORT_IN_DATABASE
define('DATA_EXPORT_UNDEFINED', 0);

/**
 * Implementation of hook_views_api().
 */
function data_views_api() {
  return array(
    'api' => '2.0',
    'path' => drupal_get_path('module', 'data'),
  );
}

/**
 * Implementation of hook_features_api().
 */
function data_features_api() {
  return array(
    'default_hook' => 'data_default',
    'file' => drupal_get_path('module', 'data') .'/data.features.inc',
  );
}

/**
 * Create a table.
 * 
 * Usage:
 * $table = data_create_table('my_table', $schema, 'My table');
 * $table->save($data);
 * 
 * @see DataTable class.
 * 
 * @param $name
 *   String that identifies the data table. It is recommended to use 
 *   data_name() to generate a table name in the data namespace. For
 *   example: $table = data_get_tabe(data_name('my_table'));
 * @param $schema
 *   Schema for the table.
 * @param $title
 *   A natural title for the table.
 * 
 * @return 
 *   A DataTable object if init could create one,
 *   FALSE if not.
 */
function data_create_table($name, $schema, $title = NULL) {
  if (_data_get_table($name, NULL, NULL, TRUE)) {
    return FALSE;
  }
  return _data_get_table($name, $schema, $title);
}

/**
 * Get a table if it exists.
 * 
 * @see DataTable class.
 * 
 * @param $name
 *   Unique name of the table.
 * 
 * @return
 *   A DataTable object if there is a table with this name,
 *   FALSE if not.
 */
function data_get_table($name) {
  if ($table = _data_get_table($name)) {
    return $table;
  }
  return FALSE;
}

/**
 * Drop a table - use this instead of $table->drop().
 */
function data_drop_table($name) {
  if ($table = data_get_table($name)) {
    $table->drop();
    _data_get_table($name, NULL, NULL, TRUE);
  }
}

/**
 * Get schema info for all data allocated tables.
 * 
 * Pull directly from database to avoid race conditions.
 */
function data_get_schema() {
  $schema = array();
  $result = db_query('SELECT name, table_schema FROM {data_tables}');
  while ($table = db_fetch_object($result)) {
    $schema[$table->name] = unserialize($table->table_schema);
  }
  return $schema;
}

/**
 * Load all data tables.
 */
function data_get_all_tables() {
  $tables = array();
  if ($tables = _data_load_table()) {
    foreach ($tables as $table_name => $table) {
      if ($table = data_get_table($table_name)) {
        $tables[$table_name] = $table;
      }
    }
  }
  return $tables;
}

/**
 * Get a list of supported field definitions.
 * 
 * This list is a sub set of Schema API data types 
 * http://drupal.org/node/159605
 * The keys are simplified handles.
 */
function data_get_field_definitions() {
  return array(
    'int' => array(
      'type' => 'int',
      'not null' => FALSE,
    ),
    'unsigned int' => array(
      'type' => 'int',
      'unsigned' => TRUE,
      'not null' => FALSE,
    ),
    'varchar' => array(
      'type' => 'varchar',
      'length' => 255,
      'not null' => FALSE,
    ),
    'text' => array(
      'type' => 'text',
      'not null' => FALSE,
    ),
  );
}

/**
 * Get a definition key into a schema API type definition.
 * 
 * If no type can be found, FALSE will be returned.
 */
function data_get_field_definition($key) {
  $definitions = data_get_field_definitions();
  if (isset($definitions[$key])) {
    return $definitions[$key];
  }
  return FALSE;
}

/**
 * Get schema API field types supported by Data module.
 */
function data_get_field_types() {
  $definitions = data_get_field_definitions();
  $types = array();
  foreach ($definitions as $def) {
    $types[$def['type']] = $def['type'];
  }
  return $types;
}

/**
 * Get a Schema API PK definition for a given field type.
 */
function data_get_pk_definition($name, $type) {
  if ($type == 'text') {
    return array($name, 255);
  }
  else {
    return $name;
  }
}

/**
 * Get a Schema API index definition for a given field type.
 * @todo: support multiple name/type combinations.
 */
function data_get_index_definition($name, $type) {
  if ($type == 'text') {
    return array(array($name, 255));
  }
  else {
    return array($name);
  }
}

/**
 * Create a table name in the data namespace.
 * @todo: make overridable.
 */
function data_name($table) {
  return 'data_table_'. $table;
}

/**
 * Create a safe name for MySQL field or table names.
 * 
 * @todo: IMPROVE.
 * 
 * - make sure all unsafe characters are removed.
 * - filter magic words.
 * - test pgsql.
 */
function data_safe_name($name) {
  $map = array(
    '.' => '_', 
    ':' => '', 
    '/' => '', 
    '-' => '_', 
    ' ' => '_',
    ',' => '_',
  );
  $simple = trim(strtolower(strip_tags($name)));
  // Limit length to 64 as per http://dev.mysql.com/doc/refman/5.0/en/identifiers.html
  $simple = substr(strtr($simple, $map), 0, 64);

  if (is_numeric($simple)) {
    // We need to escape numerics because Drupal's drupal_write_record() 
    // does not properly escape token MYSQL names.
    $simple = '__num_'. $simple;
  }
  return db_escape_table($simple);
}

/**
 * Helper function to create a natural name.
 * underscored_name -> Underscored name
 */
function data_natural_name($name) {
  return ucfirst(strtolower(str_replace('_', ' ', $name)));
}

/**
 * Helper function to generate a schema.
 * 
 * Example:
 * $table->create(data_build_schema($keys));
 * 
 * @todo: check for table name collisions
 * @todo: add type detection
 * @todo: add meta info handling
 * @todo: add primary key handling
 * @todo: may be add option to add a full fledged schema here?
 */
function data_build_schema($keys) {
  // Build the table definition.
  // Fall back to varchar if no valid type is given.
  $fields = $schema = array();
  foreach ($keys as $k => $key) {
    if ($definition = data_get_field_definition($key)) {
      $fields[data_safe_name($k)] = $definition;
    }
    else {
      $fields[data_safe_name($k)] = data_get_field_definition('varchar');
    }
  }

  $schema['fields'] = $fields;
  $schema['indexes'] = array();
  return $schema;
}

/**
 * Build a full schema api field definition.
 * 
 * @param $stub
 *   Array with at least one key 'type'.
 */
function data_build_field_definition($stub) {
  $spec = array();
  $spec['type'] = $stub['type'];
  if ($spec['type'] == 'int') {
    $spec['unsigned'] = empty($stub['unsigned']) ? FALSE : TRUE;
  }
  if ($spec['type'] == 'varchar') {
    $spec['length'] = 255;
  }
  return $spec;
}

/**
 * Export a data table. This does not export the content of a table - only its schema 
 * and any meta information (title, name, meta...).
 * 
 * @param $name
 *   The name of the table to be exported.
 * 
 * @return 
 *   Exportable code. 
 * 
 * Only available if ctools is installed.
 */
function data_export($name, $indent = '') {
  if (module_exists('ctools')) {
    ctools_include('export');
    $result = ctools_export_load_object('data_tables', 'names', array($name));
    if (isset($result[$name])) {
      return ctools_export_object('data_tables', $result[$name], $indent);
    }
  }
  return t('Export requires CTools http://drupal.org/project/ctools');
}

/**
 * Internal singleton/factory function for creating a single instance of a DataTable class.
 * 
 * Don't use this function directly. Call data_create_table() or data_get_table() instead.
 * 
 * If a schema is given, _data_get_table() creates the table objects DB structure.
 * 
 * The purpose of this function is to make sure that 
 * 
 * a) there is only a single DataTable object for accessing a specific DataTable.
 * b) there is no DataTable object that does not have an existing table.
 */
function _data_get_table($name, $schema = NULL, $title = NULL, $reset = FALSE) {
  _data_include();

  static $tables;
  // Simple way of having a way to override the class being used. 
  // This could be refined with a $type parameter in _data_get_table() and depending
  // functions.
  $class = variable_get('data_table_class', 'DataTable');
  if ($reset) {
    unset($tables[$name]);
  }

  if (!isset($tables[$name])) {
    // Try whether we can load table, then instantiate. Object will then load itself.
    if (_data_load_table($name, $reset)) {
      $tables[$name] = new $class($name);
    }
  }
  if ($schema) {
    $tables[$name] = new $class($name, $schema, $title);
  }
  return isset($tables[$name]) ? $tables[$name] : FALSE;
}

/**
 * Loads data table info from the database. Uses CTools if available.
 */
function _data_load_table($name = NULL, $reset = FALSE) {
  if (module_exists('ctools')) {
    ctools_include('export');
    if (empty($name)) {
      return ctools_export_load_object('data_tables', 'all', array(), $reset);
    }
    else {
      $tables = ctools_export_load_object('data_tables', 'names', array($name), $reset);
      if (isset($tables[$name])) {
        return $tables[$name];
      }
      return FALSE;
    }
  }
  // If CTools is not available, load directly from DB.
  if (empty($name)) {
    $result = db_query('SELECT * FROM {data_tables}');
    $tables = array();
    while ($row = db_fetch_object($result)) {
      foreach (array('table_schema', 'meta') as $key) {
        $row->$key = unserialize($row->$key);
      }
      // No export type.
      $row->export_type = DATA_EXPORT_UNDEFINED;
      $tables[$row->name] = $row;
    }
    return $tables;
  }
  if ($table = db_fetch_object(db_query('SELECT * FROM {data_tables} WHERE name = "%s"', $name))) {
      // No export type.
      $table->export_type = DATA_EXPORT_UNDEFINED;
      return $table;
  }
  return FALSE;
}

/**
 * Starts overriding a data table by copying it from the default definition into the DB.
 * This function does not have any effect if called on a table that does already exist in
 * data_tables.
 */
function _data_override($name) {
  if (!db_result(db_query('SELECT name FROM {data_tables} WHERE name = "%s"', $name))) {
    if ($table = _data_load_table($name)) {
      drupal_write_record('data_tables', $table);
    }
  }
}

/**
 * Include class file.
 */
function _data_include() {
  static $included;
  if (!$included) {
    include drupal_get_path('module', 'data') .'/data.inc';
  }
  $included = TRUE;
}