filter.module 56.3 KB
Newer Older
1 2
<?php

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

8
use Drupal\Component\Utility\String;
9
use Drupal\Core\Cache\CacheBackendInterface;
10
use Drupal\Core\Language\Language;
11
use Drupal\Core\Session\AccountInterface;
12
use Drupal\Core\Template\Attribute;
13
use Drupal\filter\FilterFormatInterface;
Dries's avatar
 
Dries committed
14

15 16
/**
 * Non-HTML markup language filters that generate HTML.
17 18
 *
 * @todo Move into \Drupal\filter\Plugin\Filter\FilterInterface
19 20 21 22 23
 */
const FILTER_TYPE_MARKUP_LANGUAGE = 0;

/**
 * HTML tag and attribute restricting filters.
24 25
 *
 * @todo Move into \Drupal\filter\Plugin\Filter\FilterInterface
26 27 28 29 30
 */
const FILTER_TYPE_HTML_RESTRICTOR = 1;

/**
 * Reversible transformation filters.
31 32
 *
 * @todo Move into \Drupal\filter\Plugin\Filter\FilterInterface
33 34 35 36 37
 */
const FILTER_TYPE_TRANSFORM_REVERSIBLE = 2;

/**
 * Irreversible transformation filters.
38 39
 *
 * @todo Move into \Drupal\filter\Plugin\Filter\FilterInterface
40 41 42
 */
const FILTER_TYPE_TRANSFORM_IRREVERSIBLE = 3;

Dries's avatar
Dries committed
43
/**
44
 * Implements hook_help().
Dries's avatar
Dries committed
45
 */
46 47
function filter_help($path, $arg) {
  switch ($path) {
48
    case 'admin/help#filter':
49 50
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
51
      $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/documentation/modules/filter/')) . '</p>';
52 53
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
54 55
      $output .= '<dt>' . t('Configuring text formats') . '</dt>';
      $output .= '<dd>' . t('Configure text formats on the <a href="@formats">Text formats page</a>. <strong>Improper text format configuration is a security risk</strong>. To ensure security, untrusted users should only have access to text formats that restrict them to either plain text or a safe set of HTML tags, since certain HTML tags can allow embedding malicious links or scripts in text. More trusted registered users may be granted permission to use less restrictive text formats in order to create rich content.', array('@formats' => url('admin/config/content/formats'))) . '</dd>';
56
      $output .= '<dt>' . t('Applying filters to text') . '</dt>';
57
      $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>';
58
      $output .= '<dt>' . t('Defining text formats') . '</dt>';
59
      $output .= '<dd>' . t('One format is included by default: <em>Plain text</em> (which removes all HTML tags). Additional formats may be created by your installation profile when you install Drupal, and more can be created by an administrator on the <a href="@text-formats">Text formats page</a>.', array('@text-formats' => url('admin/config/content/formats'))) . '</dd>';
60
      $output .= '<dt>' . t('Choosing a text format') . '</dt>';
61
      $output .= '<dd>' . t('Users with access to more than one text format can use the <em>Text format</em> widget to choose between available text formats when creating or editing multi-line content. Administrators can define the text formats available to each user role, and control the order of formats listed in the <em>Text format</em> widget on the <a href="@text-formats">Text formats page</a>.', array('@text-formats' => url('admin/config/content/formats'))) . '</dd>';
62
      $output .= '</dl>';
63
      return $output;
64

65
    case 'admin/config/content/formats':
66
      $output = '<p>' . t('Text formats define the HTML tags, code, and other formatting that can be used when entering text. <strong>Improper text format configuration is a security risk</strong>. Learn more on the <a href="@filterhelp">Filter module help page</a>.', array('@filterhelp' => url('admin/help/filter'))) . '</p>';
67
      $output .= '<p>' . t('Text formats are presented on content editing pages in the order defined on this page. The first format available to a user will be selected by default.') . '</p>';
68
      return $output;
69

70
    case 'admin/config/content/formats/manage/%':
71
      $output = '<p>' . t('A text format contains filters that change the user input, for example stripping out malicious HTML or making URLs clickable. Filters are executed from top to bottom and the order is important, since one filter may prevent another filter from doing its job. For example, when URLs are converted into links before disallowed HTML tags are removed, all links may be removed. When this happens, the order of filters may need to be re-arranged.') . '</p>';
72
      return $output;
73 74 75
  }
}

76
/**
77
 * Implements hook_theme().
78 79 80 81
 */
function filter_theme() {
  return array(
    'filter_tips' => array(
82
      'variables' => array('tips' => NULL, 'long' => FALSE),
83
      'file' => 'filter.pages.inc',
84
    ),
85 86 87
    'text_format_wrapper' => array(
      'render element' => 'element',
    ),
88
    'filter_guidelines' => array(
89
      'variables' => array('format' => NULL),
90
    ),
91 92 93
    'filter_html_image_secure_image' => array(
      'variables' => array('image' => NULL),
    ),
94 95 96 97 98 99 100 101 102
    'filter_caption' => array(
      'variables' => array(
        'node' => NULL,
        'tag' => NULL,
        'caption' => NULL,
        'align' => NULL,
      ),
      'template' => 'filter-caption',
    )
103 104 105
  );
}

106 107 108 109
/**
 * Implements hook_element_info().
 *
 * @see filter_process_format()
110
 * @see text_format_wrapper()
111 112 113 114 115 116 117 118 119 120
 */
function filter_element_info() {
  $type['text_format'] = array(
    '#process' => array('filter_process_format'),
    '#base_type' => 'textarea',
    '#theme_wrappers' => array('text_format_wrapper'),
  );
  return $type;
}

121
/**
122
 * Implements hook_menu().
123
 */
124
function filter_menu() {
125 126 127
  $items['filter/tips'] = array(
    'title' => 'Compose tips',
    'type' => MENU_SUGGESTED_ITEM,
128
    'route_name' => 'filter.tips_all',
129
  );
130
  $items['filter/tips/%'] = array(
131
    'title' => 'Compose tips',
132
    'route_name' => 'filter.tips',
133
  );
134
  $items['admin/config/content/formats'] = array(
135
    'title' => 'Text formats',
136
    'description' => 'Configure how content input by users is filtered, including allowed HTML tags. Also allows enabling of module-provided filters.',
137
    'route_name' => 'filter.admin_overview',
138
  );
139
  $items['admin/config/content/formats/list'] = array(
140
    'title' => 'List',
141 142
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
143 144 145
  $items['admin/config/content/formats/manage/%'] = array(
    'title callback' => 'entity_page_label',
    'title arguments' => array(5),
146
    'route_name' => 'filter.format_edit',
147
  );
148
  $items['admin/config/content/formats/manage/%/disable'] = array(
149
    'title' => 'Disable text format',
150
    'route_name' => 'filter.admin_disable',
151
  );
152 153 154 155
  return $items;
}

/**
156
 * Implements hook_permission().
157
 */
158
function filter_permission() {
159
  $perms['administer filters'] = array(
160
    'title' => t('Administer text formats and filters'),
161 162 163
    'description' => t('Define how text is handled by combining filters into <a href="@url">text formats</a>.', array(
      '@url' => url('admin/config/content/formats'),
    )),
164
    'restrict access' => TRUE,
165
  );
166 167 168 169

  // Generate permissions for each text format. Warn the administrator that any
  // of them are potentially unsafe.
  foreach (filter_formats() as $format) {
170 171
    if ($permission = $format->getPermissionName()) {
      $format_name_replacement = l($format->label(), 'admin/config/content/formats/manage/' . $format->id());
172
      $perms[$permission] = array(
173
        'title' => t("Use the !text_format text format", array('!text_format' => $format_name_replacement,)),
174
        'description' => String::placeholder(t('Warning: This permission may have security implications depending on how the text format is configured.')),
175 176 177 178 179 180 181
      );
    }
  }
  return $perms;
}

/**
182
 * Retrieves a list of enabled text formats, ordered by weight.
183
 *
184
 * @param \Drupal\Core\Session\AccountInterface|null $account
185
 *   (optional) If provided, only those formats that are allowed for this user
186 187
 *   account will be returned. All enabled formats will be returned otherwise.
 *   Defaults to NULL.
188
 *
189
 * @return \Drupal\filter\FilterFormatInterface[]
190 191 192 193
 *   An array of text format objects, keyed by the format ID and ordered by
 *   weight.
 *
 * @see filter_formats_reset()
Dries's avatar
Dries committed
194
 */
195
function filter_formats(AccountInterface $account = NULL) {
196
  $formats = &drupal_static(__FUNCTION__, array());
197

198
  // All available formats are cached for performance.
199
  if (!isset($formats['all'])) {
200 201
    $language_interface = \Drupal::languageManager()->getLanguage(Language::TYPE_INTERFACE);
    if ($cache = \Drupal::cache()->get("filter_formats:{$language_interface->id}")) {
202 203 204
      $formats['all'] = $cache->data;
    }
    else {
205
      $formats['all'] = \Drupal::entityManager()->getStorageController('filter_format')->loadByProperties(array('status' => TRUE));
206
      uasort($formats['all'], 'Drupal\Core\Config\Entity\ConfigEntityBase::sort');
207
      \Drupal::cache()->set("filter_formats:{$language_interface->id}", $formats['all'], CacheBackendInterface::CACHE_PERMANENT, array('filter_formats' => TRUE));
208
    }
209
  }
210

211 212 213 214 215
  // If no user was specified, return all formats.
  if (!isset($account)) {
    return $formats['all'];
  }

216
  // Build a list of user-specific formats.
217 218 219
  $account_id = $account->id();
  if (!isset($formats['user'][$account_id])) {
    $formats['user'][$account_id] = array();
220
    foreach ($formats['all'] as $format) {
221 222
      if ($format->access('view', $account)) {
        $formats['user'][$account_id][$format->format] = $format;
223 224
      }
    }
225 226
  }

227
  return $formats['user'][$account_id];
228
}
229

230
/**
231
 * Resets the text format caches.
232 233 234 235
 *
 * @see filter_formats()
 */
function filter_formats_reset() {
236
  cache()->deleteTags(array('filter_formats' => TRUE));
237 238 239 240 241 242
  drupal_static_reset('filter_formats');
}

/**
 * Retrieves a list of roles that are allowed to use a given text format.
 *
243
 * @param \Drupal\filter\FilterFormatInterface $format
244
 *   An object representing the text format.
245
 *
246
 * @return array
247 248
 *   An array of role names, keyed by role ID.
 */
249
function filter_get_roles_by_format(FilterFormatInterface $format) {
250
  // Handle the fallback format upfront (all roles have access to this format).
251
  if ($format->isFallbackFormat()) {
252
    return user_role_names();
253
  }
254
  // Do not list any roles if the permission does not exist.
255
  $permission = $format->getPermissionName();
256
  return !empty($permission) ? user_role_names(FALSE, $permission) : array();
257 258 259 260 261 262 263
}

/**
 * Retrieves a list of text formats that are allowed for a given role.
 *
 * @param $rid
 *   The user role ID to retrieve text formats for.
264
 *
265
 * @return \Drupal\filter\FilterFormatInterface[]
266 267 268 269 270 271 272 273
 *   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])) {
274
      $formats[$format->id()] = $format;
275
    }
276
  }
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
  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.
 *
296
 * @param \Drupal\Core\Session\AccountInterface|null $account
297
 *   (optional) The user account to check. Defaults to the currently logged-in
298
 *   user. Defaults to NULL.
299
 *
300
 * @return string
301 302 303 304
 *   The ID of the user's default text format.
 *
 * @see filter_fallback_format()
 */
305
function filter_default_format(AccountInterface $account = NULL) {
306 307 308 309 310 311
  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.
312 313
  $formats = filter_formats($account);
  $format = reset($formats);
314 315 316
  return $format->format;
}

317 318 319 320 321 322 323 324 325 326 327 328 329 330
/**
 * Retrieves all filter types that are used in a given text format.
 *
 * @param string $format_id
 *   A text format ID.
 *
 * @return array
 *   All filter types used by filters of a given text format.
 *
 * @throws Exception
 */
function filter_get_filter_types_by_format($format_id) {
  $filter_types = array();

331 332 333 334 335 336
  if ($format_id) {
    $filters = entity_load('filter_format', $format_id)->filters();
    foreach ($filters as $filter) {
      if ($filter->status) {
        $filter_types[] = $filter->getType();
      }
337 338 339 340 341 342
    }
  }

  return array_unique($filter_types);
}

343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
/**
 * Retrieve all HTML restrictions (tags and attributes) for a given text format.
 *
 * Note that restrictions applied to the "*" tag (the wildcard tag, i.e. all
 * tags) are treated just like any other HTML tag. That means that any
 * restrictions applied to it are not automatically applied to all other tags.
 * It is up to the caller to handle this in whatever way it sees fit; this way
 * no information granularity is lost.
 *
 * @param string $format_id
 *   A text format ID.
 *
 * @return array|FALSE
 *   An structured array as returned by FilterInterface::getHTMLRestrictions(),
 *   but with the intersection of all filters in this text format.
 *   Will either indicate blacklisting of tags or whitelisting of tags. In the
 *   latter case, it's possible that restrictions on attributes are also stored.
 *   FALSE means there are no HTML restrictions.
 */
function filter_get_html_restrictions_by_format($format_id) {
363
  $format = entity_load('filter_format', $format_id);
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 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 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 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490

  // Ignore filters that are disabled or don't have HTML restrictions.
  $filters = array_filter($format->filters()->getAll(), function($filter) {
    if (!$filter->status) {
      return FALSE;
    }
    if ($filter->getType() === FILTER_TYPE_HTML_RESTRICTOR && $filter->getHTMLRestrictions() !== FALSE) {
      return TRUE;
    }
    return FALSE;
  });

  if (empty($filters)) {
    return FALSE;
  }
  else {
    // From the set of remaining filters (they were filtered by array_filter()
    // above), collect the list of tags and attributes that are allowed by all
    // filters, i.e. the intersection of all allowed tags and attributes.
    $restrictions = array_reduce($filters, function($restrictions, $filter) {
      $new_restrictions = $filter->getHTMLRestrictions();

      // The first filter with HTML restrictions provides the initial set.
      if (!isset($restrictions)) {
        return $new_restrictions;
      }
      // Subsequent filters with an "allowed html" setting must be intersected
      // with the existing set, to ensure we only end up with the tags that are
      // allowed by *all* filters with an "allowed html" setting.
      else {
        // Track the union of forbidden (blacklisted) tags.
        if (isset($new_restrictions['forbidden_tags'])) {
          if (!isset($restrictions['forbidden_tags'])) {
            $restrictions['forbidden_tags'] = $new_restrictions['forbidden_tags'];
          }
          else {
            $restrictions['forbidden_tags'] = array_unique(array_merge($restrictions['forbidden_tags'], $new_restrictions['forbidden_tags']));
          }
        }

        // Track the intersection of allowed (whitelisted) tags.
        if (isset($restrictions['allowed'])) {
          $intersection = $restrictions['allowed'];
          foreach ($intersection as $tag => $attributes) {
            // If the current tag is not whitelisted by the new filter, then
            // it's outside of the intersection.
            if (!array_key_exists($tag, $new_restrictions['allowed'])) {
              // The exception is the asterisk (which applies to all tags): it
              // does not need to be whitelisted by every filter in order to be
              // used; not every filter needs attribute restrictions on all tags.
              if ($tag === '*') {
                continue;
              }
              unset($intersection[$tag]);
            }
            // The tag is in the intersection, but now we must calculate the
            // intersection of the allowed attributes.
            else {
              $current_attributes = $intersection[$tag];
              $new_attributes = $new_restrictions['allowed'][$tag];
              // The current intersection does not allow any attributes, never
              // allow.
              if (!is_array($current_attributes) && $current_attributes == FALSE) {
                continue;
              }
              // The new filter allows less attributes (all -> list or none).
              else if (!is_array($current_attributes) && $current_attributes == TRUE && ($new_attributes == FALSE || is_array($new_attributes))) {
                $intersection[$tag] = $new_attributes;
              }
              // The new filter allows less attributes (list -> none).
              else if (is_array($current_attributes) && $new_attributes == FALSE) {
                $intersection[$tag] = $new_attributes;
              }
              // The new filter allows more attributes; retain current.
              else if (is_array($current_attributes) && $new_attributes == TRUE) {
                continue;
              }
              // The new filter allows the same attributes; retain current.
              else if ($current_attributes == $new_attributes) {
                continue;
              }
              // Both list an array of attribute values; do an intersection,
              // where we take into account that a value of:
              //  - TRUE means the attribute value is allowed;
              //  - FALSE means the attribute value is forbidden;
              // hence we keep the ANDed result.
              else {
                $intersection[$tag] = array_intersect_key($intersection[$tag], $new_attributes);
                foreach (array_keys($intersection[$tag]) as $attribute_value) {
                  $intersection[$tag][$attribute_value] = $intersection[$tag][$attribute_value] && $new_attributes[$attribute_value];
                }
              }
            }
          }
          $restrictions['allowed'] = $intersection;
        }

        return $restrictions;
      }
    }, NULL);

    // Simplification: if we have both a (intersected) whitelist and a (unioned)
    // blacklist, then remove any tags from the whitelist that also exist in the
    // blacklist. Now the whitelist alone expresses all tag-level restrictions,
    // and we can delete the blacklist.
    if (isset($restrictions['allowed']) && isset($restrictions['forbidden_tags'])) {
      foreach ($restrictions['forbidden_tags'] as $tag) {
        if (isset($restrictions['allowed'][$tag])) {
          unset($restrictions['allowed'][$tag]);
        }
      }
      unset($restrictions['forbidden_tags']);
    }

    // Simplification: if the only remaining allowed tag is the asterisk (which
    // contains attribute restrictions that apply to all tags), and only
    // whitelisting filters were used, then effectively nothing is allowed.
    if (isset($restrictions['allowed'])) {
      if (count($restrictions['allowed']) === 1 && array_key_exists('*', $restrictions['allowed']) && !isset($restrictions['forbidden_tags'])) {
        $restrictions['allowed'] = array();
      }
    }

    return $restrictions;
  }
}

491 492
/**
 * Returns the ID of the fallback text format that all users have access to.
493 494 495
 *
 * The fallback text format is a regular text format in every respect, except
 * it does not participate in the filter permission system and cannot be
496
 * disabled. It needs to exist because any user who has permission to create
497 498 499 500 501 502 503
 * formatted content must always have at least one text format they can use.
 *
 * Because the fallback format is available to all users, it should always be
 * configured securely. For example, when the Filter module is installed, this
 * format is initialized to output plain text. Installation profiles and site
 * administrators have the freedom to configure it further.
 *
504 505 506 507 508 509
 * Note that the fallback format is completely distinct from the default format,
 * which differs per user and is simply the first format which that user has
 * access to. The default and fallback formats are only guaranteed to be the
 * same for users who do not have access to any other format; otherwise, the
 * fallback format's weight determines its placement with respect to the user's
 * other formats.
510
 *
511 512
 * Any modules implementing a format deletion functionality must not delete this
 * format.
513
 *
514 515 516
 * @return
 *   The ID of the fallback text format.
 *
517
 * @see hook_filter_format_disable()
518
 * @see filter_default_format()
519 520 521
 */
function filter_fallback_format() {
  // This variable is automatically set in the database for all installations
522
  // of Drupal. In the event that it gets disabled or deleted somehow, there
523
  // is no safe default to return, since we do not want to risk making an
524 525 526
  // existing (and potentially unsafe) text format on the site automatically
  // available to all users. Returning NULL at least guarantees that this
  // cannot happen.
527
  return \Drupal::config('filter.settings')->get('fallback_format');
528 529
}

Dries's avatar
Dries committed
530
/**
531
 * Checks if the text in a certain text format is allowed to be cached.
532 533 534 535 536
 *
 * 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.
 *
537
 * @param string $format_id
538
 *   The text format ID to check.
539
 *
540
 * @return bool
541
 *   TRUE if the given text format allows caching, FALSE otherwise.
Dries's avatar
Dries committed
542
 */
543
function filter_format_allowcache($format_id) {
544
  $format = $format_id ? entity_load('filter_format', $format_id) : FALSE;
545 546 547
  return !empty($format->cache);
}

548
/**
549
 * Runs all the enabled filters on a piece of text.
550
 *
551
 * Note: Because filters can inject JavaScript or execute PHP code, security is
552
 * vital here. When a user supplies a text format, you should validate it using
553
 * $format->access() before accepting/using it. This is normally done in the
554 555
 * validation stage of the Form API. You should for example never make a
 * preview of content in a disallowed format.
556 557
 *
 * @param $text
558
 *   The text to be filtered.
559
 * @param $format_id
560 561
 *   (optional) The format ID of the text to be filtered. If no format is
 *   assigned, the fallback format will be used. Defaults to NULL.
562
 * @param $langcode
563
 *   (optional) The language code of the text to be filtered, e.g. 'en' for
564
 *   English. This allows filters to be language aware so language specific
565
 *   text replacement can be implemented. Defaults to an empty string.
566
 * @param $cache
567 568 569 570
 *   (optional) A Boolean indicating 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.
 *   Defaults to FALSE.
571 572 573 574 575
 * @param array $filter_types_to_skip
 *   (optional) An array of filter types to skip, or an empty array (default)
 *   to skip no filter types. All of the format's filters will be applied,
 *   except for filters of the types that are marked to be skipped.
 *   FILTER_TYPE_HTML_RESTRICTOR is the only type that cannot be skipped.
576
 *
577 578 579
 * @return
 *   The filtered text.
 *
580
 * @ingroup sanitization
Dries's avatar
Dries committed
581
 */
582
function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE, $filter_types_to_skip = array()) {
583
  if (!isset($format_id)) {
584
    $format_id = filter_fallback_format();
585
  }
586
  // If the requested text format does not exist, the text cannot be filtered.
587
  if (!$format = entity_load('filter_format', $format_id)) {
588
    watchdog('filter', 'Missing text format: %format.', array('%format' => $format_id), WATCHDOG_ALERT);
589 590
    return '';
  }
591

592 593 594 595 596 597 598 599 600 601
  // Prevent FILTER_TYPE_HTML_RESTRICTOR from being skipped.
  if (in_array(FILTER_TYPE_HTML_RESTRICTOR, $filter_types_to_skip)) {
    $filter_types_to_skip = array_diff($filter_types_to_skip, array(FILTER_TYPE_HTML_RESTRICTOR));
  }

  // When certain filters should be skipped, don't perform caching.
  if ($filter_types_to_skip) {
    $cache = FALSE;
  }

602
  // Check for a cached version of this piece of text.
603
  $cache = $cache && !empty($format->cache);
604
  $cache_id = '';
605
  if ($cache) {
606
    $cache_id = $format->format . ':' . $langcode . ':' . hash('sha256', $text);
607
    if ($cached = cache('filter')->get($cache_id)) {
608 609
      return $cached->data;
    }
610
  }
611

612 613 614
  // 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
615

616
  // Get a complete list of filters, ordered properly.
617
  $filters = $format->filters();
618

619
  // Give filters the chance to escape HTML-like data such as code or formulas.
620
  foreach ($filters as $filter) {
621
    // If necessary, skip filters of a certain type.
622
    if (in_array($filter->getType(), $filter_types_to_skip)) {
623 624
      continue;
    }
625 626
    if ($filter->status) {
      $text = $filter->prepare($text, $langcode, $cache, $cache_id);
627
    }
628
  }
629

630
  // Perform filtering.
631
  foreach ($filters as $filter) {
632
    // If necessary, skip filters of a certain type.
633
    if (in_array($filter->getType(), $filter_types_to_skip)) {
634 635
      continue;
    }
636 637
    if ($filter->status) {
      $text = $filter->process($text, $langcode, $cache, $cache_id);
Dries's avatar
Dries committed
638 639
    }
  }
640

641 642 643
  // Cache the filtered text. This cache is infinitely valid. It becomes
  // obsolete when $text changes (which leads to a new $cache_id). It is
  // automatically flushed when the text format is updated.
644
  // @see \Drupal\filter\Entity\FilterFormat::save()
645
  if ($cache) {
646
    cache('filter')->set($cache_id, $text, CacheBackendInterface::CACHE_PERMANENT, array('filter_format' => $format->id()));
Dries's avatar
Dries committed
647 648 649 650 651 652
  }

  return $text;
}

/**
653 654 655
 * Expands an element into a base element with text format selector attached.
 *
 * The form element will be expanded into two separate form elements, one
656 657 658 659
 * holding the original element, and the other holding the text format
 * selector:
 * - value: Holds the original element, having its #type changed to the value
 *   of #base_type or 'textarea' by default.
660
 * - format: Holds the text format details and the text format selection,
661 662 663 664 665
 *   using the text format ID specified in #format or the user's default format
 *   by default, if NULL.
 *
 * The resulting value for the element will be an array holding the value and
 * the format. For example, the value for the body element will be:
666
 * @code
667 668
 *   $form_state['values']['body']['value'] = 'foo';
 *   $form_state['values']['body']['format'] = 'foo';
669 670 671 672 673 674
 * @endcode
 *
 * @param $element
 *   The form element to process. Properties used:
 *   - #base_type: The form element #type to use for the 'value' element.
 *     'textarea' by default.
675
 *   - #format: (optional) The text format ID to preselect. If NULL or not set,
676
 *     the default format for the current user will be used.
677
 *
Dries's avatar
Dries committed
678
 * @return
679
 *   The expanded element.
Dries's avatar
Dries committed
680
 */
681
function filter_process_format($element) {
682 683
  global $user;

684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704
  // Ensure that children appear as subkeys of this element.
  $element['#tree'] = TRUE;
  $blacklist = array(
    // Make form_builder() regenerate child properties.
    '#parents',
    '#id',
    '#name',
    // Do not copy this #process function to prevent form_builder() from
    // recursing infinitely.
    '#process',
    // Description is handled by theme_text_format_wrapper().
    '#description',
    // Ensure proper ordering of children.
    '#weight',
    // Properties already processed for the parent element.
    '#prefix',
    '#suffix',
    '#attached',
    '#processed',
    '#theme_wrappers',
  );
705
  // Move this element into sub-element 'value'.
706
  unset($element['value']);
707 708 709
  foreach (element_properties($element) as $key) {
    if (!in_array($key, $blacklist)) {
      $element['value'][$key] = $element[$key];
710
    }
711 712
  }

713 714 715 716
  $element['value']['#type'] = $element['#base_type'];
  $element['value'] += element_info($element['#base_type']);

  // Turn original element into a text format wrapper.
717
  $element['#attached']['library'][] = array('filter', 'drupal.filter');
718

719 720
  // Setup child container for the text format widget.
  $element['format'] = array(
721
    '#type' => 'container',
722
    '#attributes' => array('class' => array('filter-wrapper')),
723
  );
724

725 726 727 728 729 730 731 732 733 734 735
  // Get a list of formats that the current user has access to.
  $formats = filter_formats($user);

  // Use the default format for this user if none was selected.
  if (!isset($element['#format'])) {
    $element['#format'] = filter_default_format($user);
  }

  // If multiple text formats are available, remove the fallback. The
  // "always_show_fallback_choice" is a hidden variable that has no UI. It
  // defaults to false.
736
  if (!\Drupal::config('filter.settings')->get('always_show_fallback_choice')) {
737 738 739 740 741 742
    $fallback_format = filter_fallback_format();
    if ($element['#format'] !== $fallback_format && count($formats) > 1) {
      unset($formats[$fallback_format]);
    }
  }

743 744 745 746 747
  // Prepare text format guidelines.
  $element['format']['guidelines'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('filter-guidelines')),
    '#weight' => 20,
748
  );
749
  $options = array();
750
  foreach ($formats as $format) {
751 752
    $options[$format->id()] = $format->label();
    $element['format']['guidelines'][$format->id()] = array(
753 754
      '#theme' => 'filter_guidelines',
      '#format' => $format,
755
    );
Dries's avatar
Dries committed
756
  }
757 758

  $element['format']['format'] = array(
759 760 761
    '#type' => 'select',
    '#title' => t('Text format'),
    '#options' => $options,
762
    '#default_value' => $element['#format'],
763
    '#access' => count($formats) > 1,
764
    '#weight' => 10,
765
    '#attributes' => array('class' => array('filter-list')),
766
    '#parents' => array_merge($element['#parents'], array('format')),
767
  );
768 769 770 771

  $element['format']['help'] = array(
    '#type' => 'container',
    '#attributes' => array('class' => array('filter-help')),
772
    '#markup' => l(t('About text formats'), 'filter/tips', array('attributes' => array('target' => '_blank'))),
773
    '#weight' => 0,
774 775
  );

776
  $all_formats = filter_formats();
777 778 779 780 781 782 783
  $format_exists = isset($all_formats[$element['#format']]);
  $user_has_access = isset($formats[$element['#format']]);
  $user_is_admin = user_access('administer filters');

  // If the stored format does not exist, administrators have to assign a new
  // format.
  if (!$format_exists && $user_is_admin) {
784
    $element['format']['format']['#required'] = TRUE;
785 786 787 788 789 790 791 792 793
    $element['format']['format']['#default_value'] = NULL;
    // Force access to the format selector (it may have been denied above if
    // the user only has access to a single format).
    $element['format']['format']['#access'] = TRUE;
  }
  // Disable this widget, if the user is not allowed to use the stored format,
  // or if the stored format does not exist. The 'administer filters' permission
  // only grants access to the filter administration, not to all formats.
  elseif (!$user_has_access || !$format_exists) {
794 795 796 797 798 799
    // Overload default values into #value to make them unalterable.
    $element['value']['#value'] = $element['value']['#default_value'];
    $element['format']['format']['#value'] = $element['format']['format']['#default_value'];

    // Prepend #pre_render callback to replace field value with user notice
    // prior to rendering.
800
    $element['value'] += array('#pre_render' => array());
801 802 803 804 805 806 807
    array_unshift($element['value']['#pre_render'], 'filter_form_access_denied');

    // Cosmetic adjustments.
    if (isset($element['value']['#rows'])) {
      $element['value']['#rows'] = 3;
    }
    $element['value']['#disabled'] = TRUE;
808
    $element['value']['#resizable'] = 'none';
809 810 811 812 813 814 815 816 817 818

    // Hide the text format selector and any other child element (such as text
    // field's summary).
    foreach (element_children($element) as $key) {
      if ($key != 'value') {
        $element[$key]['#access'] = FALSE;
      }
    }
  }

819 820 821
  return $element;
}

822
/**
823
 * Render API callback: Hides the field value of 'text_format' elements.
824
 *
825 826 827
 * To not break form processing and previews if a user does not have access to
 * a stored text format, the expanded form elements in filter_process_format()
 * are forced to take over the stored #default_values for 'value' and 'format'.
828 829 830 831 832 833 834 835 836 837
 * However, to prevent the unfiltered, original #value from being displayed to
 * the user, we replace it with a friendly notice here.
 *
 * @see filter_process_format()
 */
function filter_form_access_denied($element) {
  $element['#value'] = t('This field has been disabled because you do not have sufficient permissions to edit it.');
  return $element;
}

838
/**
839
 * Returns HTML for a text format-enabled form element.
840
 *
841
 * @param array $variables
842
 *   An associative array containing:
843
 *   - element: A render element containing #children and #description.
844 845 846 847 848
 *
 * @ingroup themeable
 */
function theme_text_format_wrapper($variables) {
  $element = $variables['element'];
849
  $output = '<div class="text-format-wrapper form-item">';
850 851 852 853 854 855 856
  $output .= $element['#children'];
  if (!empty($element['#description'])) {
    $output .= '<div class="description">' . $element['#description'] . '</div>';
  }
  $output .= "</div>\n";

  return $output;
Dries's avatar
Dries committed
857 858 859
}

/**
860 861
 * Retrieves the filter tips.
 *
862
 * @param string $format_id
863 864
 *   The ID of the text format for which to retrieve tips, or -1 to return tips
 *   for all formats accessible to the current user.
865
 * @param bool $long
866 867 868
 *   (optional) Boolean indicating whether the long form of tips should be
 *   returned. Defaults to FALSE.
 *
869
 * @return array
870 871 872 873
 *   An associative array of filtering tips, keyed by filter name. Each
 *   filtering tip is an associative array with elements:
 *   - tip: Tip text.
 *   - id: Filter ID.
Dries's avatar
Dries committed
874
 */
875
function _filter_tips($format_id, $long = FALSE) {
876 877 878
  global $user;

  $formats = filter_formats($user);
Dries's avatar
Dries committed
879 880 881

  $tips = array();

882
  // If only listing one format, extract it from the $formats array.
883 884
  if ($format_id != -1) {
    $formats = array($formats[$format_id]);
885 886
  }

Dries's avatar
Dries committed
887
  foreach ($formats as $format) {
888
    foreach ($format->filters() as $name => $filter) {
889 890
      if ($filter->status) {
        $tip = $filter->tips($long);
891
        if (isset($tip)) {
892
          $tips[$format->label()][$name] = array('tip' => $tip, 'id' => $name);
893
        }
Dries's avatar
Dries committed
894 895 896 897 898 899 900
      }
    }
  }

  return $tips;
}

901 902 903
/**
 * Parses an HTML snippet and returns it as a DOM object.
 *
904 905 906 907
 * 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.
908
 *
909
 * @param $text
910 911 912
 *   The partial (X)HTML snippet to load. Invalid markup will be corrected on
 *   import.
 *
913 914 915 916
 * @return
 *   A DOMDocument that represents the loaded (X)HTML snippet.
 */
function filter_dom_load($text) {
917
  $dom_document = new DOMDocument();
918
  // Ignore warnings during HTML soup loading.
919
  @$dom_document->loadHTML('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /></head><body>' . $text . '</body></html>');
920

921
  return $dom_document;
922 923 924 925 926
}

/**
 * Converts a DOM object back to an HTML snippet.
 *
927 928 929
 * 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.
930
 *
931 932 933
 * @param $dom_document
 *   A DOMDocument object to serialize, only the tags below
 *   the first <body> node will be converted.
934
 *
935 936 937 938 939 940
 * @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 = '';
941

942
  foreach ($body_node->getElementsByTagName('script') as $node) {
943 944 945
    filter_dom_serialize_escape_cdata_element($dom_document, $node);
  }

946
  foreach ($body_node->getElementsByTagName('style') as $node) {
947 948
    filter_dom_serialize_escape_cdata_element($dom_document, $node, '/*', '*/');
  }
949

950 951 952
  foreach ($body_node->childNodes as $child_node) {
    $body_content .= $dom_document->saveXML($child_node);
  }
953
  return $body_content;
954
}
Dries's avatar
Dries committed
955

956 957
/**
 * Adds comments around the <!CDATA section in a dom element.
958
 *
959 960 961
 * DOMDocument::loadHTML in filter_dom_load() makes CDATA sections from the
 * contents of inline script and style tags.  This can cause HTML 4 browsers to
 * throw exceptions.
962
 *
963
 * This function attempts to solve the problem by creating a DocumentFragment
964
 * and imitating the behavior in drupal_get_js(), commenting the CDATA tag.