filter.module 49.2 KB
Newer Older
1
2
3
<?php
// $Id$

Dries's avatar
   
Dries committed
4
5
6
7
8
/**
 * @file
 * Framework for handling filtering of content.
 */

Dries's avatar
Dries committed
9
/**
10
 * Implements hook_help().
Dries's avatar
Dries committed
11
 */
12
13
function filter_help($path, $arg) {
  switch ($path) {
14
    case 'admin/help#filter':
15
16
17
18
19
20
21
22
23
24
25
26
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Filter module allows administrators to configure text formats. A text format defines the HTML tags, codes, and other input allowed in content and comments, and is a key feature in guarding against potentially damaging input from malicious users. For more information, see the online handbook entry for <a href="@filter">Filter module</a>.', array('@filter' => 'http://drupal.org/handbook/modules/filter/')) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Applying filters to text') . '</dt>';
      $output .= '<dd>' . t('Each text format uses filters to manipulate text, and most formats apply several different filters to text in a specific order. Each filter is designed for a specific purpose, and generally either adds, removes or transforms elements within user-entered text before it is displayed. A filter does not change the actual content, but instead, modifies it temporarily before it is displayed. One filter may remove unapproved HTML tags, while another automatically adds HTML to make URLS display as clickable links.') . '</dd>';
      $output .= '<dt>' . t('Defining text formats') . '</dt>';
      $output .= '<dd>' . t('There are three formats included by default; <em>Filtered HTML</em> (which allows only an administrator-approved subset of HTML tags), <em>Full HTML</em> (which allows the full set of HTML tags), and <em>Plain text</em> (which removes all HTML tags). Additional formats may be created by an administrator on the <a href="@text-formats">Text formats page</a>.', array('@text-formats' => url('admin/config/content/formats'))) . '</dd>';
      $output .= '<dt>' . t('Choosing a text format') . '</dt>';
      $output .= '<dd>' . t('Users with access to more than one text format can use the <em>Text format</em> fieldset to choose between available text formats when creating or editing multi-line content. Administrators can determine the text formats available to each user role, and control the order of formats listed in the <em>Text format</em> fieldset on the <a href="@text-formats">Text formats page</a>.', array('@text-formats' => url('admin/config/content/formats'))) . '</dd>';
      $output .= '</dl>';
27
      return $output;
28
    case 'admin/config/content/formats':
29
30
      $output = '<p>' . t("Control which HTML tags and other formatting can be used for text input. Don't allow too much formatting for untrusted users. This can be a serious security risk.") . '</p>';
      $output .= '<p>' . t('Text formats are presented in the order you arrange them below. Configure a text format to change its behavior.') . '</p>';
31
      return $output;
32
33
34
35
36
    case 'admin/config/content/formats/%':
      return '<p>' . t('Every <em>filter</em> performs one particular change on the user input, for example stripping out malicious HTML or making URLs clickable. Choose which filters you want to apply to text in this format. If you notice some filters are causing conflicts in the output, you can <a href="@rearrange">rearrange them</a>.', array('@rearrange' => url('admin/config/content/formats/' . $arg[4] . '/order'))) . '</p>';
    case 'admin/config/content/formats/%/configure':
      return '<p>' . t('If you cannot find the settings for a certain filter, make sure you have enabled it on the <a href="@url">edit tab</a> first.', array('@url' => url('admin/config/content/formats/' . $arg[4]))) . '</p>';
    case 'admin/config/content/formats/%/order':
37
38
      $output = '<p>' . t('Because of the flexible filtering system, you might encounter a situation where one filter prevents another from doing its job. For example: a word in an URL gets converted into a glossary term, before the URL can be converted to a clickable link. When this happens, rearrange the order of the filters.') . '</p>';
      $output .= '<p>' . t("Filters are executed from top-to-bottom. To change the order of the filters, modify the values in the <em>Weight</em> column or grab a drag-and-drop handle under the <em>Name</em> column and drag filters to new locations in the list. (Grab a handle by clicking and holding the mouse while hovering over a handle icon.) Remember that your changes will not be saved until you click the <em>Save configuration</em> button at the bottom of the page.") . '</p>';
39
      return $output;
40
41
42
  }
}

43
/**
44
 * Implements hook_theme().
45
46
47
48
 */
function filter_theme() {
  return array(
    'filter_admin_overview' => array(
49
      'render element' => 'form',
50
      'file' => 'filter.admin.inc',
51
52
    ),
    'filter_admin_order' => array(
53
      'render element' => 'form',
54
      'file' => 'filter.admin.inc',
55
56
    ),
    'filter_tips' => array(
57
      'variables' => array('tips' => NULL, 'long' => FALSE),
58
      'file' => 'filter.pages.inc',
59
60
    ),
    'filter_tips_more_info' => array(
61
      'variables' => array(),
62
    ),
63
    'filter_guidelines' => array(
64
      'variables' => array('format' => NULL),
65
    ),
66
67
68
  );
}

69
/**
70
 * Implements hook_menu().
71
 */
72
function filter_menu() {
73
74
75
76
77
78
79
  $items['filter/tips'] = array(
    'title' => 'Compose tips',
    'page callback' => 'filter_tips_long',
    'access callback' => TRUE,
    'type' => MENU_SUGGESTED_ITEM,
    'file' => 'filter.pages.inc',
  );
80
  $items['admin/config/content/formats'] = array(
81
    'title' => 'Text formats',
82
    'description' => 'Configure how content input by users is filtered, including allowed HTML tags. Also allows enabling of module-provided filters.',
83
84
85
    'page callback' => 'drupal_get_form',
    'page arguments' => array('filter_admin_overview'),
    'access arguments' => array('administer filters'),
86
    'file' => 'filter.admin.inc',
87
  );
88
  $items['admin/config/content/formats/list'] = array(
89
    'title' => 'List',
90
91
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
92
  $items['admin/config/content/formats/add'] = array(
93
    'title' => 'Add text format',
94
    'page callback' => 'filter_admin_format_page',
95
    'access arguments' => array('administer filters'),
96
    'type' => MENU_LOCAL_ACTION,
97
    'weight' => 1,
98
    'file' => 'filter.admin.inc',
99
  );
100
  $items['admin/config/content/formats/%filter_format'] = array(
101
    'type' => MENU_CALLBACK,
102
    'title callback' => 'filter_admin_format_title',
103
    'title arguments' => array(4),
104
    'page callback' => 'filter_admin_format_page',
105
    'page arguments' => array(4),
106
    'access arguments' => array('administer filters'),
107
    'file' => 'filter.admin.inc',
108
  );
109
  $items['admin/config/content/formats/%filter_format/edit'] = array(
110
    'title' => 'Edit',
111
112
113
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => 0,
  );
114
  $items['admin/config/content/formats/%filter_format/configure'] = array(
115
    'title' => 'Configure',
116
    'page callback' => 'filter_admin_configure_page',
117
    'page arguments' => array(4),
118
    'access arguments' => array('administer filters'),
119
120
    'type' => MENU_LOCAL_TASK,
    'weight' => 1,
121
    'file' => 'filter.admin.inc',
122
  );
123
  $items['admin/config/content/formats/%filter_format/order'] = array(
124
    'title' => 'Rearrange',
125
    'page callback' => 'filter_admin_order_page',
126
    'page arguments' => array(4),
127
    'access arguments' => array('administer filters'),
128
129
    'type' => MENU_LOCAL_TASK,
    'weight' => 2,
130
    'file' => 'filter.admin.inc',
131
  );
132
  $items['admin/config/content/formats/%filter_format/delete'] = array(
133
134
    'title' => 'Delete text format',
    'page callback' => 'drupal_get_form',
135
    'page arguments' => array('filter_admin_delete', 4),
136
137
    'access callback' => '_filter_delete_format_access',
    'access arguments' => array(4),
138
139
140
    'type' => MENU_CALLBACK,
    'file' => 'filter.admin.inc',
  );
141
142
143
  return $items;
}

144
145
146
147
148
149
150
151
152
153
154
155
156
157
/**
 * Access callback for deleting text formats.
 *
 * @param $format
 *   A text format object.
 * @return
 *   TRUE if the text format can be deleted by the current user, FALSE
 *   otherwise.
 */
function _filter_delete_format_access($format) {
  // The fallback format can never be deleted.
  return user_access('administer filters') && ($format->format != filter_fallback_format());
}

158
159
160
/**
 * Load a text format object from the database.
 *
161
 * @param $format_id
162
163
164
165
166
 *   The format ID.
 *
 * @return
 *   A fully-populated text format object.
 */
167
function filter_format_load($format_id) {
168
  $formats = filter_formats();
169
  return isset($formats[$format_id]) ? $formats[$format_id] : FALSE;
170
171
}

172
173
174
175
/**
 * Save a text format object to the database.
 *
 * @param $format
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 *   A format object using the properties:
 *   - 'name': The title of the text format.
 *   - 'format': (optional) The internal ID of the text format. If omitted, a
 *     new text format is created.
 *   - 'roles': (optional) An associative array containing the roles allowed to
 *     access/use the text format.
 *   - 'filters': (optional) An associative, multi-dimensional array of filters
 *     assigned to the text format, using the properties:
 *     - 'weight': The weight of the filter in the text format.
 *     - 'status': A boolean indicating whether the filter is enabled in the
 *       text format.
 *     - 'module': The name of the module implementing the filter.
 *     - 'settings': (optional) An array of configured settings for the filter.
 *       See hook_filter_info() for details.
190
 */
191
function filter_format_save(&$format) {
192
  $format->name = trim($format->name);
193
  $format->cache = _filter_format_is_cacheable($format);
194
195
196

  // Add a new text format.
  if (empty($format->format)) {
197
    $return = drupal_write_record('filter_format', $format);
198
199
  }
  else {
200
    $return = drupal_write_record('filter_format', $format, 'format');
201
202
  }

203
  // Get the current filters in the format, to add new filters to the bottom.
204
  $current = ($return != SAVED_NEW ? filter_list_format($format->format) : array());
205
  $filter_info = filter_get_filters();
206
  // Programmatic saves may not contain any filters.
207
208
209
  if (!isset($format->filters)) {
    $format->filters = array();
  }
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
  foreach ($filter_info as $name => $filter) {
    // As of now, only programmatic saves may contain weight (see below). If
    // there is no weight, either fall back to the currently stored weight or
    // add new filters to the bottom.
    if (!isset($format->filters[$name]['weight'])) {
      $format->filters[$name]['weight'] = isset($current[$name]->weight) ? $current[$name]->weight : 10;
    }
    $format->filters[$name]['status'] = isset($format->filters[$name]['status']) ? $format->filters[$name]['status'] : 0;
    $format->filters[$name]['module'] = $filter['module'];

    // Since filter configuration/order lives on separate pages, there may be no
    // filter settings contained. In that case, we either fall back to currently
    // stored settings, default settings (if existent), or an empty array.
    // @see http://drupal.org/node/558666
    // If settings were passed, only ensure default settings.
    if (isset($format->filters[$name]['settings'])) {
      if (isset($filter['default settings'])) {
        $format->filters[$name]['settings'] = array_merge($filter['default settings'], $format->filters[$name]['settings']);
      }
229
    }
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
    // If we have existing settings, take them over directly.
    elseif (isset($current[$name]->settings)) {
      $format->filters[$name]['settings'] = $current[$name]->settings;
    }
    // Otherwise, use default settings or fall back to an empty array.
    else {
      $format->filters[$name]['settings'] = isset($filter['default settings']) ? $filter['default settings'] : array();
    }

    $fields = array();
    $fields['weight'] = $format->filters[$name]['weight'];
    $fields['status'] = $format->filters[$name]['status'];
    $fields['module'] = $format->filters[$name]['module'];
    $fields['settings'] = serialize($format->filters[$name]['settings']);

245
246
247
248
249
250
251
    db_merge('filter')
      ->key(array(
        'format' => $format->format,
        'name' => $name,
      ))
      ->fields($fields)
      ->execute();
252
253
  }

254
  if ($return == SAVED_NEW) {
255
256
257
258
    module_invoke_all('filter_format_insert', $format);
  }
  else {
    module_invoke_all('filter_format_update', $format);
259
260
261
262
263
264
265
266
    // Explicitly indicate that the format was updated. We need to do this
    // since if the filters were updated but the format object itself was not,
    // the call to drupal_write_record() above would not return an indication
    // that anything had changed.
    $return = SAVED_UPDATED;

    // Clear the filter cache whenever a text format is updated.
    cache_clear_all($format->format . ':', 'cache_filter', TRUE);
267
268
  }

269
  filter_formats_reset();
270

271
  return $return;
272
273
274
275
276
277
}

/**
 * Delete a text format.
 *
 * @param $format
278
 *   The text format object to be deleted.
279
280
281
 */
function filter_format_delete($format) {
  db_delete('filter_format')
282
    ->condition('format', $format->format)
283
284
    ->execute();
  db_delete('filter')
285
    ->condition('format', $format->format)
286
287
    ->execute();

288
  // Allow modules to react on text format deletion.
289
290
  $fallback = filter_format_load(filter_fallback_format());
  module_invoke_all('filter_format_delete', $format, $fallback);
291

292
  filter_formats_reset();
293
  cache_clear_all($format->format . ':', 'cache_filter', TRUE);
294
295
}

296
/**
297
 * Display a text format form title.
298
299
300
301
302
 */
function filter_admin_format_title($format) {
  return $format->name;
}

303
/**
304
 * Implements hook_permission().
305
 */
306
function filter_permission() {
307
  $perms['administer filters'] = array(
308
309
    'title' => t('Administer and use any text formats and filters'),
    'description' => theme('placeholder', array('text' => t('Warning: This permission may have security implications depending on how the text format is configured.'))),
310
  );
311
312
313
314
315
316
317
318

  // Generate permissions for each text format. Warn the administrator that any
  // of them are potentially unsafe.
  foreach (filter_formats() as $format) {
    $permission = filter_permission_name($format);
    if (!empty($permission)) {
      // Only link to the text format configuration page if the user who is
      // viewing this will have access to that page.
319
      $format_name_replacement = user_access('administer filters') ? l($format->name, 'admin/config/content/formats/' . $format->format) : theme('placeholder', array('text' => $format->name));
320
      $perms[$permission] = array(
321
322
        'title' => t("Use the !text_format text format", array('!text_format' => $format_name_replacement,)),
        'description' => theme('placeholder', array('text' => t('Warning: This permission may have security implications depending on how the text format is configured.'))),
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
      );
    }
  }
  return $perms;
}

/**
 * Returns the machine-readable permission name for a provided text format.
 *
 * @param $format
 *   An object representing a text format.
 * @return
 *   The machine-readable permission name, or FALSE if the provided text format
 *   is malformed or is the fallback format (which is available to all users).
 */
function filter_permission_name($format) {
  if (isset($format->format) && $format->format != filter_fallback_format()) {
    return 'use text format ' . $format->format;
  }
  return FALSE;
343
344
}

345
/**
346
 * Implements hook_cron().
347
348
349
350
351
352
353
 *
 * Expire outdated filter cache entries
 */
function filter_cron() {
  cache_clear_all(NULL, 'cache_filter');
}

Dries's avatar
Dries committed
354
/**
355
 * Retrieve a list of text formats, ordered by weight.
356
357
 *
 * @param $account
358
359
 *   (optional) If provided, only those formats that are allowed for this user
 *   account will be returned. All formats will be returned otherwise.
360
 * @return
361
362
363
364
 *   An array of text format objects, keyed by the format ID and ordered by
 *   weight.
 *
 * @see filter_formats_reset()
Dries's avatar
Dries committed
365
 */
366
function filter_formats($account = NULL) {
367
  $formats = &drupal_static(__FUNCTION__, array());
368

369
370
  // Statically cache all existing formats upfront.
  if (!isset($formats['all'])) {
371
372
373
374
375
376
    $formats['all'] = db_select('filter_format', 'ff')
      ->addTag('translatable')
      ->fields('ff')
      ->orderBy('weight')
      ->execute()
      ->fetchAllAssoc('format');
377
  }
378

379
380
381
382
383
384
  // Build a list of user-specific formats.
  if (isset($account) && !isset($formats['user'][$account->uid])) {
    $formats['user'][$account->uid] = array();
    foreach ($formats['all'] as $format) {
      if (filter_access($format, $account)) {
        $formats['user'][$account->uid][$format->format] = $format;
385
386
      }
    }
387
388
389
390
  }

  return isset($account) ? $formats['user'][$account->uid] : $formats['all'];
}
391

392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
/**
 * Resets the static cache of all text formats.
 *
 * @see filter_formats()
 */
function filter_formats_reset() {
  drupal_static_reset('filter_list_format');
  drupal_static_reset('filter_formats');
}

/**
 * Retrieves a list of roles that are allowed to use a given text format.
 *
 * @param $format
 *   An object representing the text format.
 * @return
 *   An array of role names, keyed by role ID.
 */
function filter_get_roles_by_format($format) {
  // Handle the fallback format upfront (all roles have access to this format).
  if ($format->format == filter_fallback_format()) {
    return user_roles();
414
  }
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
  // Do not list any roles if the permission does not exist.
  $permission = filter_permission_name($format);
  return !empty($permission) ? user_roles(FALSE, $permission) : array();
}

/**
 * Retrieves a list of text formats that are allowed for a given role.
 *
 * @param $rid
 *   The user role ID to retrieve text formats for.
 * @return
 *   An array of text format objects that are allowed for the role, keyed by
 *   the text format ID and ordered by weight.
 */
function filter_get_formats_by_role($rid) {
  $formats = array();
  foreach (filter_formats() as $format) {
    $roles = filter_get_roles_by_format($format);
    if (isset($roles[$rid])) {
      $formats[$format->format] = $format;
    }
436
  }
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
  return $formats;
}

/**
 * Returns the ID of the default text format for a particular user.
 *
 * The default text format is the first available format that the user is
 * allowed to access, when the formats are ordered by weight. It should
 * generally be used as a default choice when presenting the user with a list
 * of possible text formats (for example, in a node creation form).
 *
 * Conversely, when existing content that does not have an assigned text format
 * needs to be filtered for display, the default text format is the wrong
 * choice, because it is not guaranteed to be consistent from user to user, and
 * some trusted users may have an unsafe text format set by default, which
 * should not be used on text of unknown origin. Instead, the fallback format
 * returned by filter_fallback_format() should be used, since that is intended
 * to be a safe, consistent format that is always available to all users.
 *
 * @param $account
 *   (optional) The user account to check. Defaults to the currently logged-in
 *   user.
 * @return
 *   The ID of the user's default text format.
 *
 * @see filter_fallback_format()
 */
function filter_default_format($account = NULL) {
  global $user;
  if (!isset($account)) {
    $account = $user;
  }
  // Get a list of formats for this user, ordered by weight. The first one
  // available is the user's default format.
471
472
  $formats = filter_formats($account);
  $format = reset($formats);
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
  return $format->format;
}

/**
 * Returns the ID of the fallback text format that all users have access to.
 */
function filter_fallback_format() {
  // This variable is automatically set in the database for all installations
  // of Drupal. In the event that it gets deleted somehow, there is no safe
  // default to return, since we do not want to risk making an existing (and
  // potentially unsafe) text format on the site automatically available to all
  // users. Returning NULL at least guarantees that this cannot happen.
  return variable_get('filter_fallback_format');
}

/**
 * Returns the title of the fallback text format.
 */
function filter_fallback_format_title() {
  $fallback_format = filter_format_load(filter_fallback_format());
  return filter_admin_format_title($fallback_format);
494
}
495

496
/**
497
 * Return a list of all filters provided by modules.
498
 */
499
500
501
502
503
504
505
function filter_get_filters() {
  $filters = &drupal_static(__FUNCTION__, array());

  if (empty($filters)) {
    foreach (module_implements('filter_info') as $module) {
      $info = module_invoke($module, 'filter_info');
      if (isset($info) && is_array($info)) {
506
507
508
509
        // Assign the name of the module implementing the filters.
        foreach (array_keys($info) as $name) {
          $info[$name]['module'] = $module;
        }
510
        $filters = array_merge($filters, $info);
511
      }
Dries's avatar
   
Dries committed
512
    }
513
514
    // Allow modules to alter filter definitions.
    drupal_alter('filter_info', $filters);
Dries's avatar
   
Dries committed
515

516
517
    uasort($filters, '_filter_list_cmp');
  }
518
519
520
521
522
523
524
525

  return $filters;
}

/**
 * Helper function for sorting the filter list by filter name.
 */
function _filter_list_cmp($a, $b) {
526
  return strcmp($a['title'], $b['title']);
Dries's avatar
   
Dries committed
527
528
}

Dries's avatar
Dries committed
529
/**
530
 * Check if text in a certain text format is allowed to be cached.
531
532
533
534
535
536
537
538
539
 *
 * This function can be used to check whether the result of the filtering
 * process can be cached. A text format may allow caching depending on the
 * filters enabled.
 *
 * @param $format_id
 *   The text format ID to check.
 * @return
 *   TRUE if the given text format allows caching, FALSE otherwise.
Dries's avatar
Dries committed
540
 */
541
function filter_format_allowcache($format_id) {
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
  $format = filter_format_load($format_id);
  return !empty($format->cache);
}

/**
 * Helper function to determine whether the output of a given text format can be cached.
 *
 * The output of a given text format can be cached when all enabled filters in
 * the text format allow caching.
 *
 * @param $format
 *   The text format object to check.
 * @return
 *   TRUE if all the filters enabled in the given text format allow caching,
 *   FALSE otherwise.
 *
 * @see filter_format_save()
 */
function _filter_format_is_cacheable($format) {
  if (empty($format->filters)) {
    return TRUE;
  }
  $filter_info = filter_get_filters();
  foreach ($format->filters as $name => $filter) {
    // By default, 'cache' is TRUE for all filters unless specified otherwise.
567
    if (!empty($filter['status']) && isset($filter_info[$name]['cache']) && !$filter_info[$name]['cache']) {
568
569
      return FALSE;
    }
570
  }
571
  return TRUE;
572
573
574
}

/**
575
 * Retrieve a list of filters for a given text format.
576
 *
577
578
579
580
581
 * Note that this function returns all associated filters regardless of whether
 * they are enabled or disabled. All functions working with the filter
 * information outside of filter administration should test for $filter->status
 * before performing actions with the filter.
 *
582
 * @param $format_id
583
 *   The format ID to retrieve filters for.
584
 *
585
 * @return
586
587
 *   An array of filter objects associated to the given text format, keyed by
 *   filter name.
588
 */
589
function filter_list_format($format_id) {
590
  $filters = &drupal_static(__FUNCTION__, array());
591
  $filter_info = filter_get_filters();
592

593
594
595
596
597
598
599
  if (!isset($filters['all'])) {
    $result = db_query('SELECT * FROM {filter} ORDER BY weight, module, name');
    foreach ($result as $record) {
      $filters['all'][$record->format][$record->name] = $record;
    }
  }

600
  if (!isset($filters[$format_id])) {
601
    $format_filters = array();
602
    foreach ($filters['all'][$format_id] as $name => $filter) {
603
604
      if (isset($filter_info[$name])) {
        $filter->title = $filter_info[$name]['title'];
605
        // Unpack stored filter settings.
606
        $filter->settings = (isset($filter->settings) ? unserialize($filter->settings) : array());
607

608
        $format_filters[$name] = $filter;
Dries's avatar
   
Dries committed
609
610
      }
    }
611
    $filters[$format_id] = $format_filters;
Dries's avatar
   
Dries committed
612
613
  }

614
  return isset($filters[$format_id]) ? $filters[$format_id] : array();
615
616
}

617
/**
618
 * Run all the enabled filters on a piece of text.
619
 *
620
 * Note: Because filters can inject JavaScript or execute PHP code, security is
621
622
623
624
 * vital here. When a user supplies a text format, you should validate it using
 * filter_access() before accepting/using it. This is normally done in the
 * validation stage of the Form API. You should for example never make a preview
 * of content in a disallowed format.
625
626
 *
 * @param $text
627
 *   The text to be filtered.
628
629
 * @param $format_id
 *   The format id of the text to be filtered. If no format is assigned, the
630
 *   fallback format will be used.
631
 * @param $langcode
632
633
634
 *   Optional: the language code of the text to be filtered, e.g. 'en' for
 *   English. This allows filters to be language aware so language specific
 *   text replacement can be implemented.
635
636
637
638
 * @param $cache
 *   Boolean whether to cache the filtered output in the {cache_filter} table.
 *   The caller may set this to FALSE when the output is already cached
 *   elsewhere to avoid duplicate cache lookups and storage.
Dries's avatar
Dries committed
639
 */
640
641
642
function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE) {
  if (empty($format_id)) {
    $format_id = filter_fallback_format();
643
  }
644
  $format = filter_format_load($format_id);
645

646
  // Check for a cached version of this piece of text.
647
  $cache = $cache && !empty($format->cache);
648
  $cache_id = '';
649
  if ($cache) {
650
    $cache_id = $format->format . ':' . $langcode . ':' . md5($text);
651
652
653
    if ($cached = cache_get($cache_id, 'cache_filter')) {
      return $cached->data;
    }
654
  }
655

656
657
658
  // Convert all Windows and Mac newlines to a single newline, so filters only
  // need to deal with one possibility.
  $text = str_replace(array("\r\n", "\r"), "\n", $text);
Dries's avatar
   
Dries committed
659

660
  // Get a complete list of filters, ordered properly.
661
  $filters = filter_list_format($format->format);
662
  $filter_info = filter_get_filters();
663

664
  // Give filters the chance to escape HTML-like data such as code or formulas.
665
  foreach ($filters as $name => $filter) {
666
667
668
    if ($filter->status && isset($filter_info[$name]['prepare callback']) && function_exists($filter_info[$name]['prepare callback'])) {
      $function = $filter_info[$name]['prepare callback'];
      $text = $function($text, $filter, $format, $langcode, $cache, $cache_id);
669
    }
670
  }
671

672
  // Perform filtering.
673
  foreach ($filters as $name => $filter) {
674
675
676
    if ($filter->status && isset($filter_info[$name]['process callback']) && function_exists($filter_info[$name]['process callback'])) {
      $function = $filter_info[$name]['process callback'];
      $text = $function($text, $filter, $format, $langcode, $cache, $cache_id);
Dries's avatar
Dries committed
677
678
    }
  }
679
680

  // Store in cache with a minimum expiration time of 1 day.
681
  if ($cache) {
682
    cache_set($cache_id, $text, 'cache_filter', REQUEST_TIME + (60 * 60 * 24));
Dries's avatar
Dries committed
683
684
685
686
687
688
  }

  return $text;
}

/**
689
 * Generates a selector for choosing a format in a form.
Dries's avatar
Dries committed
690
 *
691
 * @param $selected_format
692
693
 *   The ID of the format that is currently selected; uses the default format
 *   for the current user if not provided.
694
 * @param $weight
695
 *   The weight of the form element within the form.
696
 * @param $parents
697
698
699
 *   The parents array of the element. Required when defining multiple text
 *   formats on a single form or having a different parent than 'format'.
 *
Dries's avatar
Dries committed
700
 * @return
701
702
703
 *   Form API array for the form element.
 *
 * @ingroup forms
Dries's avatar
Dries committed
704
 */
705
706
707
708
709
710
711
712
713
714
function filter_form($selected_format = NULL, $weight = NULL, $parents = array('format')) {
  global $user;

  // Use the default format for this user if none was selected.
  if (empty($selected_format)) {
    $selected_format = filter_default_format($user);
  }

  // Get a list of formats that the current user has access to.
  $formats = filter_formats($user);
715
716
717

  drupal_add_js('misc/form.js');
  drupal_add_css(drupal_get_path('module', 'filter') . '/filter.css');
718
  $element_id = drupal_html_id('edit-' . implode('-', $parents));
719

720
  $form = array(
721
722
    '#type' => 'fieldset',
    '#weight' => $weight,
723
    '#attributes' => array('class' => array('filter-wrapper')),
724
  );
725
726
727
728
729
730
731
732
  $form['format_guidelines'] = array(
    '#prefix' => '<div id="' . $element_id . '-guidelines" class="filter-guidelines">',
    '#suffix' => '</div>',
    '#weight' => 2,
  );
  foreach ($formats as $format) {
    $options[$format->format] = $format->name;
    $form['format_guidelines'][$format->format] = array(
733
      '#markup' => theme('filter_guidelines', array('format' => $format)),
734
    );
Dries's avatar
Dries committed
735
  }
736
737
738
739
  $form['format'] = array(
    '#type' => 'select',
    '#title' => t('Text format'),
    '#options' => $options,
740
    '#default_value' => $selected_format,
741
742
743
    '#parents' => $parents,
    '#access' => count($formats) > 1,
    '#id' => $element_id,
744
    '#attributes' => array('class' => array('filter-list')),
745
746
747
748
749
750
751
752
  );
  $form['format_help'] = array(
    '#prefix' => '<div id="' . $element_id . '-help" class="filter-help">',
    '#markup' => theme('filter_tips_more_info'),
    '#suffix' => '</div>',
    '#weight' => 1,
  );

753
  return $form;
Dries's avatar
Dries committed
754
755
756
}

/**
757
 * Checks if a user has access to a particular text format.
758
759
 *
 * @param $format
760
 *   An object representing the text format.
761
762
763
764
765
766
 * @param $account
 *   (optional) The user account to check access for; if omitted, the currently
 *   logged-in user is used.
 *
 * @return
 *   Boolean TRUE if the user is allowed to access the given format.
Dries's avatar
Dries committed
767
 */
768
function filter_access($format, $account = NULL) {
769
770
771
  global $user;
  if (!isset($account)) {
    $account = $user;
Dries's avatar
Dries committed
772
  }
773
774
775
776
  // Handle special cases up front. All users have access to the fallback
  // format, and administrators have access to all formats.
  if (user_access('administer filters', $account) || $format->format == filter_fallback_format()) {
    return TRUE;
Dries's avatar
Dries committed
777
  }
778
779
780
781
  // Check the permission if one exists; otherwise, we have a non-existent
  // format so we return FALSE.
  $permission = filter_permission_name($format);
  return !empty($permission) && user_access($permission, $account);
Dries's avatar
Dries committed
782
}
783

Dries's avatar
Dries committed
784
785
786
/**
 * Helper function for fetching filter tips.
 */
787
function _filter_tips($format_id, $long = FALSE) {
788
789
790
  global $user;

  $formats = filter_formats($user);
791
  $filter_info = filter_get_filters();
Dries's avatar
Dries committed
792
793
794

  $tips = array();

795
  // If only listing one format, extract it from the $formats array.
796
797
  if ($format_id != -1) {
    $formats = array($formats[$format_id]);
798
799
  }

Dries's avatar
Dries committed
800
801
802
  foreach ($formats as $format) {
    $filters = filter_list_format($format->format);
    $tips[$format->name] = array();
803
    foreach ($filters as $name => $filter) {
804
      if ($filter->status && isset($filter_info[$name]['tips callback']) && function_exists($filter_info[$name]['tips callback'])) {
805
806
        $tip = $filter_info[$name]['tips callback']($filter, $format, $long);
        $tips[$format->name][$name] = array('tip' => $tip, 'id' => $name);
Dries's avatar
Dries committed
807
808
809
810
811
812
813
      }
    }
  }

  return $tips;
}

814
815
816
817
818
819
820
/**
 * Parses an HTML snippet and returns it as a DOM object.
 *
 * This function loads the body part of a partial (X)HTML document
 * and returns a full DOMDocument object that represents this document.
 * You can use filter_dom_serialize() to serialize this DOMDocument
 * back to a XHTML snippet.
821
 *
822
823
824
825
826
827
828
 * @param $text
 *   The partial (X)HTML snippet to load. Invalid mark-up
 *   will be corrected on import.
 * @return
 *   A DOMDocument that represents the loaded (X)HTML snippet.
 */
function filter_dom_load($text) {
829
830
831
832
  // Suppress all libxml warnings during loading of HTML.
  libxml_use_internal_errors(TRUE);
  $document = new DOMDocument();
  $document->loadHTML('<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /></head><body>' . $text . '</body></html>');
833

834
  return $document;
835
836
837
838
839
840
841
842
843
844
}

/**
 * Converts a DOM object back to an HTML snippet.
 *
 * The function serializes the body part of a DOMDocument
 * back to an XHTML snippet.
 *
 * The resulting XHTML snippet will be properly formatted
 * to be compatible with HTML user agents.
845
 *
846
847
848
849
850
851
852
853
854
855
856
857
858
859
 * @param $dom_document
 *   A DOMDocument object to serialize, only the tags below
 *   the first <body> node will be converted.
 * @return
 *   A valid (X)HTML snippet, as a string.
 */
function filter_dom_serialize($dom_document) {
  $body_node = $dom_document->getElementsByTagName('body')->item(0);
  $body_content = '';
  foreach ($body_node->childNodes as $child_node) {
    $body_content .= $dom_document->saveXML($child_node);
  }
  return preg_replace('|<([^>]*)/>|i', '<$1 />', $body_content);
}
Dries's avatar
Dries committed
860

861
862
863
864
865
866
/**
 * Format a link to the more extensive filter tips.
 *
 * @ingroup themeable
 */
function theme_filter_tips_more_info() {
867
868
869
870
871
872
  return '<p>' . l(t('More information about text formats'), 'filter/tips') . '</p>';
}

/**
 * Format guidelines for a text format.
 *
873
874
875
876
 * @param $variables
 *   An associative array containing:
 *   - format: An object representing a text format.
 *
877
878
 * @ingroup themeable
 */
879
880
881
function theme_filter_guidelines($variables) {
  $format = $variables['format'];

882
  $name = isset($format->name) ? '<label>' . $format->name . ':</label>' : '';
883
  return '<div id="filter-guidelines-' . $format->format . '" class="filter-guidelines-item">' . $name . theme('filter_tips', array('tips' => _filter_tips($format->format, FALSE))) . '</div>';
884
885
}

Dries's avatar
Dries committed
886
887
888
889
890
891
/**
 * @name Standard filters
 * @{
 * Filters implemented by the filter.module.
 */

892
/**
893
 * Implements hook_filter_info().
894
 */
895
function filter_filter_info() {
896
897
  $filters['filter_html'] = array(
    'title' => t('Limit allowed HTML tags'),
898
899
900
    'description' => t('Allows you to restrict the HTML tags the user can use. It will also remove harmful content such as JavaScript events, JavaScript URLs and CSS styles from those tags that are not removed.'),
    'process callback' => '_filter_html',
    'settings callback' => '_filter_html_settings',
901
902
903
904
905
    'default settings' => array(
      'allowed_html' => '<a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>',
      'filter_html_help' => 1,
      'filter_html_nofollow' => 0,
    ),
906
    'tips callback' => '_filter_html_tips',
907
  );
908
909
  $filters['filter_autop'] = array(
    'title' => t('Convert line breaks'),
910
911
    'description' => t('Converts line breaks into HTML (i.e. &lt;br&gt; and &lt;p&gt;) tags.'),
    'process callback' => '_filter_autop',
912
    'tips callback' => '_filter_autop_tips',
913
  );
914
915
  $filters['filter_url'] = array(
    'title' => t('Convert URLs into links'),
916
917
918
    'description' => t('Turns web and e-mail addresses into clickable links.'),
    'process callback' => '_filter_url',
    'settings callback' => '_filter_url_settings',
919
920
921
    'default settings' => array(
      'filter_url_length' => 72,
    ),
922
    'tips callback' => '_filter_url_tips',
923
  );
924
925
  $filters['filter_htmlcorrector'] = array(
    'title' =>  t('Correct broken HTML'),
926
927
928
    'description' => t('Corrects faulty and chopped off HTML in postings.'),
    'process callback' => '_filter_htmlcorrector',
  );
929
930
  $filters['filter_html_escape'] = array(
    'title' => t('Escape all HTML'),
931
932
    'description' => t('Escapes all HTML tags, so they will be visible instead of being effective.'),
    'process callback' => '_filter_html_escape',
933
    'tips callback' => '_filter_html_escape_tips',
934
935
  );
  return $filters;
Dries's avatar
Dries committed
936
937
938
}

/**
939
 * Settings callback for the HTML filter.
Dries's avatar
Dries committed
940
 */
941
function _filter_html_settings($form, &$form_state, $filter, $format, $defaults) {
942
  $settings['allowed_html'] = array(
Dries's avatar
-Patch    
Dries committed
943
944
    '#type' => 'textfield',
    '#title' => t('Allowed HTML tags'),
945
    '#default_value' => isset($filter->settings['allowed_html']) ? $filter->settings['allowed_html'] : $defaults['allowed_html'],
Dries's avatar
-Patch    
Dries committed
946
    '#size' => 64,
947
    '#maxlength' => 1024,
948
    '#description' => t('Specify a list of tags which should not be stripped. (Note that JavaScript event attributes are always stripped.)'),
Dries's avatar
-Patch    
Dries committed
949
  );
950
  $settings['filter_html_help'] = array(
Dries's avatar
-Patch    
Dries committed
951
952
    '#type' => 'checkbox',
    '#title' => t('Display HTML help'),
953
    '#default_value' => isset($filter->settings['filter_html_help']) ? $filter->settings['filter_html_help'] : $defaults['filter_html_help'],
Dries's avatar
-Patch    
Dries committed
954
955
    '#description' => t('If enabled, Drupal will display some basic HTML help in the long filter tips.'),
  );
956
  $settings['filter_html_nofollow'] = array(
Dries's avatar
-Patch    
Dries committed
957
958
    '#type' => 'checkbox',
    '#title' => t('Spam link deterrent'),
959
    '#default_value' => isset($filter->settings['filter_html_nofollow']) ? $filter->settings['filter_html_nofollow'] : $defaults['filter_html_nofollow'],
Dries's avatar
-Patch    
Dries committed
960
961
    '#description' => t('If enabled, Drupal will add rel="nofollow" to all links, as a measure to reduce the effectiveness of spam links. Note: this will also prevent valid links from being followed by search engines, therefore it is likely most effective when enabled for anonymous users.'),
  );
962
  return $settings;
Dries's avatar
Dries committed
963
964
965
966
967
}

/**
 * HTML filter. Provides filtering of input into accepted HTML.
 */
968
969
function _filter_html($text, $filter) {
  $allowed_tags = preg_split('/\s+|<|>/', $filter->settings['allowed_html'], -1, PREG_SPLIT_NO_EMPTY);
970
  $text = filter_xss($text, $allowed_tags);
Dries's avatar
Dries committed
971

972
  if ($filter->settings['filter_html_nofollow']) {
973
974
975
976
977
978
    $html_dom = filter_dom_load($text);
    $links = $html_dom->getElementsByTagName('a');
    foreach($links as $link) {
      $link->setAttribute('rel', 'nofollow');
    }
    $text = filter_dom_serialize($html_dom);
Dries's avatar
Dries committed
979
980
981
982
983
  }

  return trim($text);
}

984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
/**
 * Filter tips callback for HTML filter.
 */
function _filter_html_tips($filter, $format, $long = FALSE) {
  global $base_url;

  if (!($allowed_html = $filter->settings['allowed_html'])) {
    return;
  }
  $output = t('Allowed HTML tags: @tags', array('@tags' => $allowed_html));
  if (!$long) {
    return $output;
  }

  $output = '<p>' . $output . '</p>';
  if (!$filter->settings['filter_html_help']) {
    return $output;
  }

  $output .= '<p>' . t('This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy. This table provides examples for each tag that is enabled on this site.') . '</p>';
  $output .= '<p>' . t('For more information see W3C\'s <a href="@html-specifications">HTML Specifications</a> or use your favorite search engine to find other sites that explain HTML.', array('@html-specifications' => 'http://www.w3.org/TR/html/')) . '</p>';
  $tips = array(
    'a' => array(t('Anchors are used to make links to other pages.'), '<a href="' . $base_url . '">' . variable_get('site_name', 'Drupal') . '</a>'),
    'br' => array(t('By default line break tags are automatically added, so use this tag to add additional ones. Use of this tag is different because it is not used with an open/close pair like all the others. Use the extra " /" inside the tag to maintain XHTML 1.0 compatibility'), t('Text with <br />line break')),
    'p' => array(t('By default paragraph tags are automatically added, so use this tag to add additional ones.'), '<p>' . t('Paragraph one.') . '</p> <p>' . t('Paragraph two.') . '</p>'),
    'strong' => array(t('Strong'), '<strong>' . t('Strong') . '</strong>'),
    'em' => array(t('Emphasized'), '<em>' . t('Emphasized') . '</em>'),
    'cite' => array(t('Cited'), '<cite>' . t('Cited') . '</cite>'),
    'code' => array(t('Coded text used to show programming source code'), '<code>' . t('Coded') . '</code>'),
    'b' => array(t('Bolded'), '<b>' . t('Bolded') . '</b>'),
    'u' => array(t('Underlined'), '<u>' . t('Underlined') . '</u>'),
    'i' => array(t('Italicized'), '<i>' . t('Italicized') . '</i>'),
    'sup' => array(t('Superscripted'), t('<sup>Super</sup>scripted')),
    'sub' => array(t('Subscripted'), t('<sub>Sub</sub>scripted')),
    'pre' => array(t('Preformatted'), '<pre>' . t('Preformatted') . '</pre>'),
    'abbr' => array(t('Abbreviation'), t('<abbr title="Abbreviation">Abbrev.</abbr>')),
    'acronym' => array(t('Acronym'), t('<acronym title="Three-Letter Acronym">TLA</acronym>')),
    'blockquote' => array(t('Block quoted'), '<blockquote>' . t('Block quoted') . '</blockquote>'),
    'q' => array(t('Quoted inline'), '<q>' . t('Quoted inline') . '</q>'),
    // Assumes and describes tr, td, th.
    'table' => array(t('Table'), '<table> <tr><th>' . t('Table header') . '</th></tr> <tr><td>' . t('Table cell') . '</td></tr> </table>'),
    'tr' => NULL, 'td' => NULL, 'th' => NULL,
    'del' => array(t('Deleted'), '<del>' . t('Deleted') . '</del>'),
    'ins' => array(t('Inserted'), '<ins>' . t('Inserted') . '</ins>'),
     // Assumes and describes li.
    'ol' => array(t('Ordered list - use the &lt;li&gt; to begin each list item'), '<ol> <li>' . t('First item') . '</li> <li>' . t('Second item') . '</li> </ol>'),
    'ul' => array(t('Unordered list - use the &lt;li&gt; to begin each list item'), '<ul> <li>' . t('First item') . '</li> <li>' . t('Second item') . '</li> </ul>'),
    'li' => NULL,
    // Assumes and describes dt and dd.
    'dl' => array(t('Definition lists are similar to other HTML lists. &lt;dl&gt; begins the definition list, &lt;dt&gt; begins the definition term and &lt;dd&gt; begins the definition description.'), '<dl> <dt>' . t('First term') . '</dt> <dd>' . t('First definition') . '</dd> <dt>' . t('Second term') . '</dt> <dd>' . t('Second definition') . '</dd> </dl>'),
    'dt' => NULL, 'dd' => NULL,
    'h1' => array(t('Heading'), '<h1>' . t('Title') . '</h1>'),
    'h2' => array(t('Heading'), '<h2>' . t('Subtitle') . '</h2>'),
    'h3' => array(t('Heading'), '<h3>' . t('Subtitle three') . '</