Project

General

Profile

Paste
Download (307 KB) Statistics
| Branch: | Revision:

root / drupal7 / includes / common.inc @ 01f36513

1
<?php
2

    
3
/**
4
 * @file
5
 * Common functions that many Drupal modules will need to reference.
6
 *
7
 * The functions that are critical and need to be available even when serving
8
 * a cached page are instead located in bootstrap.inc.
9
 */
10

    
11
/**
12
 * @defgroup php_wrappers PHP wrapper functions
13
 * @{
14
 * Functions that are wrappers or custom implementations of PHP functions.
15
 *
16
 * Certain PHP functions should not be used in Drupal. Instead, Drupal's
17
 * replacement functions should be used.
18
 *
19
 * For example, for improved or more secure UTF8-handling, or RFC-compliant
20
 * handling of URLs in Drupal.
21
 *
22
 * For ease of use and memorizing, all these wrapper functions use the same name
23
 * as the original PHP function, but prefixed with "drupal_". Beware, however,
24
 * that not all wrapper functions support the same arguments as the original
25
 * functions.
26
 *
27
 * You should always use these wrapper functions in your code.
28
 *
29
 * Wrong:
30
 * @code
31
 *   $my_substring = substr($original_string, 0, 5);
32
 * @endcode
33
 *
34
 * Correct:
35
 * @code
36
 *   $my_substring = drupal_substr($original_string, 0, 5);
37
 * @endcode
38
 *
39
 * @}
40
 */
41

    
42
/**
43
 * Return status for saving which involved creating a new item.
44
 */
45
define('SAVED_NEW', 1);
46

    
47
/**
48
 * Return status for saving which involved an update to an existing item.
49
 */
50
define('SAVED_UPDATED', 2);
51

    
52
/**
53
 * Return status for saving which deleted an existing item.
54
 */
55
define('SAVED_DELETED', 3);
56

    
57
/**
58
 * The default group for system CSS files added to the page.
59
 */
60
define('CSS_SYSTEM', -100);
61

    
62
/**
63
 * The default group for module CSS files added to the page.
64
 */
65
define('CSS_DEFAULT', 0);
66

    
67
/**
68
 * The default group for theme CSS files added to the page.
69
 */
70
define('CSS_THEME', 100);
71

    
72
/**
73
 * The default group for JavaScript and jQuery libraries added to the page.
74
 */
75
define('JS_LIBRARY', -100);
76

    
77
/**
78
 * The default group for module JavaScript code added to the page.
79
 */
80
define('JS_DEFAULT', 0);
81

    
82
/**
83
 * The default group for theme JavaScript code added to the page.
84
 */
85
define('JS_THEME', 100);
86

    
87
/**
88
 * Error code indicating that the request exceeded the specified timeout.
89
 *
90
 * @see drupal_http_request()
91
 */
92
define('HTTP_REQUEST_TIMEOUT', -1);
93

    
94
/**
95
 * @defgroup block_caching Block Caching
96
 * @{
97
 * Constants that define each block's caching state.
98
 *
99
 * Modules specify how their blocks can be cached in their hook_block_info()
100
 * implementations. Caching can be turned off (DRUPAL_NO_CACHE), managed by the
101
 * module declaring the block (DRUPAL_CACHE_CUSTOM), or managed by the core
102
 * Block module. If the Block module is managing the cache, you can specify that
103
 * the block is the same for every page and user (DRUPAL_CACHE_GLOBAL), or that
104
 * it can change depending on the page (DRUPAL_CACHE_PER_PAGE) or by user
105
 * (DRUPAL_CACHE_PER_ROLE or DRUPAL_CACHE_PER_USER). Page and user settings can
106
 * be combined with a bitwise-binary or operator; for example,
107
 * DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE means that the block can change
108
 * depending on the user role or page it is on.
109
 *
110
 * The block cache is cleared in cache_clear_all(), and uses the same clearing
111
 * policy than page cache (node, comment, user, taxonomy added or updated...).
112
 * Blocks requiring more fine-grained clearing might consider disabling the
113
 * built-in block cache (DRUPAL_NO_CACHE) and roll their own.
114
 *
115
 * Note that user 1 is excluded from block caching.
116
 */
117

    
118
/**
119
 * The block should not get cached.
120
 *
121
 * This setting should be used:
122
 * - For simple blocks (notably those that do not perform any db query), where
123
 *   querying the db cache would be more expensive than directly generating the
124
 *   content.
125
 * - For blocks that change too frequently.
126
 */
127
define('DRUPAL_NO_CACHE', -1);
128

    
129
/**
130
 * The block is handling its own caching in its hook_block_view().
131
 *
132
 * This setting is useful when time based expiration is needed or a site uses a
133
 * node access which invalidates standard block cache.
134
 */
135
define('DRUPAL_CACHE_CUSTOM', -2);
136

    
137
/**
138
 * The block or element can change depending on the user's roles.
139
 *
140
 * This is the default setting for blocks, used when the block does not specify
141
 * anything.
142
 */
143
define('DRUPAL_CACHE_PER_ROLE', 0x0001);
144

    
145
/**
146
 * The block or element can change depending on the user.
147
 *
148
 * This setting can be resource-consuming for sites with large number of users,
149
 * and thus should only be used when DRUPAL_CACHE_PER_ROLE is not sufficient.
150
 */
151
define('DRUPAL_CACHE_PER_USER', 0x0002);
152

    
153
/**
154
 * The block or element can change depending on the page being viewed.
155
 */
156
define('DRUPAL_CACHE_PER_PAGE', 0x0004);
157

    
158
/**
159
 * The block or element is the same for every user and page that it is visible.
160
 */
161
define('DRUPAL_CACHE_GLOBAL', 0x0008);
162

    
163
/**
164
 * @} End of "defgroup block_caching".
165
 */
166

    
167
/**
168
 * Adds content to a specified region.
169
 *
170
 * @param $region
171
 *   Page region the content is added to.
172
 * @param $data
173
 *   Content to be added.
174
 */
175
function drupal_add_region_content($region = NULL, $data = NULL) {
176
  static $content = array();
177

    
178
  if (isset($region) && isset($data)) {
179
    $content[$region][] = $data;
180
  }
181
  return $content;
182
}
183

    
184
/**
185
 * Gets assigned content for a given region.
186
 *
187
 * @param $region
188
 *   A specified region to fetch content for. If NULL, all regions will be
189
 *   returned.
190
 * @param $delimiter
191
 *   Content to be inserted between imploded array elements.
192
 */
193
function drupal_get_region_content($region = NULL, $delimiter = ' ') {
194
  $content = drupal_add_region_content();
195
  if (isset($region)) {
196
    if (isset($content[$region]) && is_array($content[$region])) {
197
      return implode($delimiter, $content[$region]);
198
    }
199
  }
200
  else {
201
    foreach (array_keys($content) as $region) {
202
      if (is_array($content[$region])) {
203
        $content[$region] = implode($delimiter, $content[$region]);
204
      }
205
    }
206
    return $content;
207
  }
208
}
209

    
210
/**
211
 * Gets the name of the currently active installation profile.
212
 *
213
 * When this function is called during Drupal's initial installation process,
214
 * the name of the profile that's about to be installed is stored in the global
215
 * installation state. At all other times, the standard Drupal systems variable
216
 * table contains the name of the current profile, and we can call
217
 * variable_get() to determine what one is active.
218
 *
219
 * @return $profile
220
 *   The name of the installation profile.
221
 */
222
function drupal_get_profile() {
223
  global $install_state;
224

    
225
  if (isset($install_state['parameters']['profile'])) {
226
    $profile = $install_state['parameters']['profile'];
227
  }
228
  else {
229
    $profile = variable_get('install_profile', 'standard');
230
  }
231

    
232
  return $profile;
233
}
234

    
235

    
236
/**
237
 * Sets the breadcrumb trail for the current page.
238
 *
239
 * @param $breadcrumb
240
 *   Array of links, starting with "home" and proceeding up to but not including
241
 *   the current page.
242
 */
243
function drupal_set_breadcrumb($breadcrumb = NULL) {
244
  $stored_breadcrumb = &drupal_static(__FUNCTION__);
245

    
246
  if (isset($breadcrumb)) {
247
    $stored_breadcrumb = $breadcrumb;
248
  }
249
  return $stored_breadcrumb;
250
}
251

    
252
/**
253
 * Gets the breadcrumb trail for the current page.
254
 */
255
function drupal_get_breadcrumb() {
256
  $breadcrumb = drupal_set_breadcrumb();
257

    
258
  if (!isset($breadcrumb)) {
259
    $breadcrumb = menu_get_active_breadcrumb();
260
  }
261

    
262
  return $breadcrumb;
263
}
264

    
265
/**
266
 * Returns a string containing RDF namespace declarations for use in XML and
267
 * XHTML output.
268
 */
269
function drupal_get_rdf_namespaces() {
270
  $xml_rdf_namespaces = array();
271

    
272
  // Serializes the RDF namespaces in XML namespace syntax.
273
  if (function_exists('rdf_get_namespaces')) {
274
    foreach (rdf_get_namespaces() as $prefix => $uri) {
275
      $xml_rdf_namespaces[] = 'xmlns:' . $prefix . '="' . $uri . '"';
276
    }
277
  }
278
  return count($xml_rdf_namespaces) ? "\n  " . implode("\n  ", $xml_rdf_namespaces) : '';
279
}
280

    
281
/**
282
 * Adds output to the HEAD tag of the HTML page.
283
 *
284
 * This function can be called as long as the headers aren't sent. Pass no
285
 * arguments (or NULL for both) to retrieve the currently stored elements.
286
 *
287
 * @param $data
288
 *   A renderable array. If the '#type' key is not set then 'html_tag' will be
289
 *   added as the default '#type'.
290
 * @param $key
291
 *   A unique string key to allow implementations of hook_html_head_alter() to
292
 *   identify the element in $data. Required if $data is not NULL.
293
 *
294
 * @return
295
 *   An array of all stored HEAD elements.
296
 *
297
 * @see theme_html_tag()
298
 */
299
function drupal_add_html_head($data = NULL, $key = NULL) {
300
  $stored_head = &drupal_static(__FUNCTION__);
301

    
302
  if (!isset($stored_head)) {
303
    // Make sure the defaults, including Content-Type, come first.
304
    $stored_head = _drupal_default_html_head();
305
  }
306

    
307
  if (isset($data) && isset($key)) {
308
    if (!isset($data['#type'])) {
309
      $data['#type'] = 'html_tag';
310
    }
311
    $stored_head[$key] = $data;
312
  }
313
  return $stored_head;
314
}
315

    
316
/**
317
 * Returns elements that are always displayed in the HEAD tag of the HTML page.
318
 */
319
function _drupal_default_html_head() {
320
  // Add default elements. Make sure the Content-Type comes first because the
321
  // IE browser may be vulnerable to XSS via encoding attacks from any content
322
  // that comes before this META tag, such as a TITLE tag.
323
  $elements['system_meta_content_type'] = array(
324
    '#type' => 'html_tag',
325
    '#tag' => 'meta',
326
    '#attributes' => array(
327
      'http-equiv' => 'Content-Type',
328
      'content' => 'text/html; charset=utf-8',
329
    ),
330
    // Security: This always has to be output first.
331
    '#weight' => -1000,
332
  );
333
  // Show Drupal and the major version number in the META GENERATOR tag.
334
  // Get the major version.
335
  list($version, ) = explode('.', VERSION);
336
  $elements['system_meta_generator'] = array(
337
    '#type' => 'html_tag',
338
    '#tag' => 'meta',
339
    '#attributes' => array(
340
      'name' => 'Generator',
341
      'content' => 'Drupal ' . $version . ' (http://drupal.org)',
342
    ),
343
  );
344
  // Also send the generator in the HTTP header.
345
  $elements['system_meta_generator']['#attached']['drupal_add_http_header'][] = array('X-Generator', $elements['system_meta_generator']['#attributes']['content']);
346
  return $elements;
347
}
348

    
349
/**
350
 * Retrieves output to be displayed in the HEAD tag of the HTML page.
351
 */
352
function drupal_get_html_head() {
353
  $elements = drupal_add_html_head();
354
  drupal_alter('html_head', $elements);
355
  return drupal_render($elements);
356
}
357

    
358
/**
359
 * Adds a feed URL for the current page.
360
 *
361
 * This function can be called as long the HTML header hasn't been sent.
362
 *
363
 * @param $url
364
 *   An internal system path or a fully qualified external URL of the feed.
365
 * @param $title
366
 *   The title of the feed.
367
 */
368
function drupal_add_feed($url = NULL, $title = '') {
369
  $stored_feed_links = &drupal_static(__FUNCTION__, array());
370

    
371
  if (isset($url)) {
372
    $stored_feed_links[$url] = theme('feed_icon', array('url' => $url, 'title' => $title));
373

    
374
    drupal_add_html_head_link(array(
375
      'rel' => 'alternate',
376
      'type' => 'application/rss+xml',
377
      'title' => $title,
378
      // Force the URL to be absolute, for consistency with other <link> tags
379
      // output by Drupal.
380
      'href' => url($url, array('absolute' => TRUE)),
381
    ));
382
  }
383
  return $stored_feed_links;
384
}
385

    
386
/**
387
 * Gets the feed URLs for the current page.
388
 *
389
 * @param $delimiter
390
 *   A delimiter to split feeds by.
391
 */
392
function drupal_get_feeds($delimiter = "\n") {
393
  $feeds = drupal_add_feed();
394
  return implode($feeds, $delimiter);
395
}
396

    
397
/**
398
 * @defgroup http_handling HTTP handling
399
 * @{
400
 * Functions to properly handle HTTP responses.
401
 */
402

    
403
/**
404
 * Processes a URL query parameter array to remove unwanted elements.
405
 *
406
 * @param $query
407
 *   (optional) An array to be processed. Defaults to $_GET.
408
 * @param $exclude
409
 *   (optional) A list of $query array keys to remove. Use "parent[child]" to
410
 *   exclude nested items. Defaults to array('q').
411
 * @param $parent
412
 *   Internal use only. Used to build the $query array key for nested items.
413
 *
414
 * @return
415
 *   An array containing query parameters, which can be used for url().
416
 */
417
function drupal_get_query_parameters(array $query = NULL, array $exclude = array('q'), $parent = '') {
418
  // Set defaults, if none given.
419
  if (!isset($query)) {
420
    $query = $_GET;
421
  }
422
  // If $exclude is empty, there is nothing to filter.
423
  if (empty($exclude)) {
424
    return $query;
425
  }
426
  elseif (!$parent) {
427
    $exclude = array_flip($exclude);
428
  }
429

    
430
  $params = array();
431
  foreach ($query as $key => $value) {
432
    $string_key = ($parent ? $parent . '[' . $key . ']' : $key);
433
    if (isset($exclude[$string_key])) {
434
      continue;
435
    }
436

    
437
    if (is_array($value)) {
438
      $params[$key] = drupal_get_query_parameters($value, $exclude, $string_key);
439
    }
440
    else {
441
      $params[$key] = $value;
442
    }
443
  }
444

    
445
  return $params;
446
}
447

    
448
/**
449
 * Splits a URL-encoded query string into an array.
450
 *
451
 * @param $query
452
 *   The query string to split.
453
 *
454
 * @return
455
 *   An array of URL decoded couples $param_name => $value.
456
 */
457
function drupal_get_query_array($query) {
458
  $result = array();
459
  if (!empty($query)) {
460
    foreach (explode('&', $query) as $param) {
461
      $param = explode('=', $param, 2);
462
      $result[$param[0]] = isset($param[1]) ? rawurldecode($param[1]) : '';
463
    }
464
  }
465
  return $result;
466
}
467

    
468
/**
469
 * Parses an array into a valid, rawurlencoded query string.
470
 *
471
 * This differs from http_build_query() as we need to rawurlencode() (instead of
472
 * urlencode()) all query parameters.
473
 *
474
 * @param $query
475
 *   The query parameter array to be processed, e.g. $_GET.
476
 * @param $parent
477
 *   Internal use only. Used to build the $query array key for nested items.
478
 *
479
 * @return
480
 *   A rawurlencoded string which can be used as or appended to the URL query
481
 *   string.
482
 *
483
 * @see drupal_get_query_parameters()
484
 * @ingroup php_wrappers
485
 */
486
function drupal_http_build_query(array $query, $parent = '') {
487
  $params = array();
488

    
489
  foreach ($query as $key => $value) {
490
    $key = $parent ? $parent . rawurlencode('[' . $key . ']') : rawurlencode($key);
491

    
492
    // Recurse into children.
493
    if (is_array($value)) {
494
      $params[] = drupal_http_build_query($value, $key);
495
    }
496
    // If a query parameter value is NULL, only append its key.
497
    elseif (!isset($value)) {
498
      $params[] = $key;
499
    }
500
    else {
501
      // For better readability of paths in query strings, we decode slashes.
502
      $params[] = $key . '=' . str_replace('%2F', '/', rawurlencode($value));
503
    }
504
  }
505

    
506
  return implode('&', $params);
507
}
508

    
509
/**
510
 * Prepares a 'destination' URL query parameter for use with drupal_goto().
511
 *
512
 * Used to direct the user back to the referring page after completing a form.
513
 * By default the current URL is returned. If a destination exists in the
514
 * previous request, that destination is returned. As such, a destination can
515
 * persist across multiple pages.
516
 *
517
 * @return
518
 *   An associative array containing the key:
519
 *   - destination: The path provided via the destination query string or, if
520
 *     not available, the current path.
521
 *
522
 * @see current_path()
523
 * @see drupal_goto()
524
 */
525
function drupal_get_destination() {
526
  $destination = &drupal_static(__FUNCTION__);
527

    
528
  if (isset($destination)) {
529
    return $destination;
530
  }
531

    
532
  if (isset($_GET['destination'])) {
533
    $destination = array('destination' => $_GET['destination']);
534
  }
535
  else {
536
    $path = $_GET['q'];
537
    $query = drupal_http_build_query(drupal_get_query_parameters());
538
    if ($query != '') {
539
      $path .= '?' . $query;
540
    }
541
    $destination = array('destination' => $path);
542
  }
543
  return $destination;
544
}
545

    
546
/**
547
 * Parses a URL string into its path, query, and fragment components.
548
 *
549
 * This function splits both internal paths like @code node?b=c#d @endcode and
550
 * external URLs like @code https://example.com/a?b=c#d @endcode into their
551
 * component parts. See
552
 * @link http://tools.ietf.org/html/rfc3986#section-3 RFC 3986 @endlink for an
553
 * explanation of what the component parts are.
554
 *
555
 * Note that, unlike the RFC, when passed an external URL, this function
556
 * groups the scheme, authority, and path together into the path component.
557
 *
558
 * @param string $url
559
 *   The internal path or external URL string to parse.
560
 *
561
 * @return array
562
 *   An associative array containing:
563
 *   - path: The path component of $url. If $url is an external URL, this
564
 *     includes the scheme, authority, and path.
565
 *   - query: An array of query parameters from $url, if they exist.
566
 *   - fragment: The fragment component from $url, if it exists.
567
 *
568
 * @see drupal_goto()
569
 * @see l()
570
 * @see url()
571
 * @see http://tools.ietf.org/html/rfc3986
572
 *
573
 * @ingroup php_wrappers
574
 */
575
function drupal_parse_url($url) {
576
  $options = array(
577
    'path' => NULL,
578
    'query' => array(),
579
    'fragment' => '',
580
  );
581

    
582
  // External URLs: not using parse_url() here, so we do not have to rebuild
583
  // the scheme, host, and path without having any use for it.
584
  if (strpos($url, '://') !== FALSE) {
585
    // Split off everything before the query string into 'path'.
586
    $parts = explode('?', $url);
587
    $options['path'] = $parts[0];
588
    // If there is a query string, transform it into keyed query parameters.
589
    if (isset($parts[1])) {
590
      $query_parts = explode('#', $parts[1]);
591
      parse_str($query_parts[0], $options['query']);
592
      // Take over the fragment, if there is any.
593
      if (isset($query_parts[1])) {
594
        $options['fragment'] = $query_parts[1];
595
      }
596
    }
597
  }
598
  // Internal URLs.
599
  else {
600
    // parse_url() does not support relative URLs, so make it absolute. E.g. the
601
    // relative URL "foo/bar:1" isn't properly parsed.
602
    $parts = parse_url('http://example.com/' . $url);
603
    // Strip the leading slash that was just added.
604
    $options['path'] = substr($parts['path'], 1);
605
    if (isset($parts['query'])) {
606
      parse_str($parts['query'], $options['query']);
607
    }
608
    if (isset($parts['fragment'])) {
609
      $options['fragment'] = $parts['fragment'];
610
    }
611
  }
612
  // The 'q' parameter contains the path of the current page if clean URLs are
613
  // disabled. It overrides the 'path' of the URL when present, even if clean
614
  // URLs are enabled, due to how Apache rewriting rules work. The path
615
  // parameter must be a string.
616
  if (isset($options['query']['q']) && is_string($options['query']['q'])) {
617
    $options['path'] = $options['query']['q'];
618
    unset($options['query']['q']);
619
  }
620

    
621
  return $options;
622
}
623

    
624
/**
625
 * Encodes a Drupal path for use in a URL.
626
 *
627
 * For aesthetic reasons slashes are not escaped.
628
 *
629
 * Note that url() takes care of calling this function, so a path passed to that
630
 * function should not be encoded in advance.
631
 *
632
 * @param $path
633
 *   The Drupal path to encode.
634
 */
635
function drupal_encode_path($path) {
636
  return str_replace('%2F', '/', rawurlencode($path));
637
}
638

    
639
/**
640
 * Sends the user to a different page.
641
 *
642
 * This issues an on-site HTTP redirect. The function makes sure the redirected
643
 * URL is formatted correctly.
644
 *
645
 * Usually the redirected URL is constructed from this function's input
646
 * parameters. However you may override that behavior by setting a
647
 * destination in either the $_REQUEST-array (i.e. by using
648
 * the query string of an URI) This is used to direct the user back to
649
 * the proper page after completing a form. For example, after editing
650
 * a post on the 'admin/content'-page or after having logged on using the
651
 * 'user login'-block in a sidebar. The function drupal_get_destination()
652
 * can be used to help set the destination URL.
653
 *
654
 * Drupal will ensure that messages set by drupal_set_message() and other
655
 * session data are written to the database before the user is redirected.
656
 *
657
 * This function ends the request; use it instead of a return in your menu
658
 * callback.
659
 *
660
 * @param $path
661
 *   (optional) A Drupal path or a full URL, which will be passed to url() to
662
 *   compute the redirect for the URL.
663
 * @param $options
664
 *   (optional) An associative array of additional URL options to pass to url().
665
 * @param $http_response_code
666
 *   (optional) The HTTP status code to use for the redirection, defaults to
667
 *   302. The valid values for 3xx redirection status codes are defined in
668
 *   @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3 RFC 2616 @endlink
669
 *   and the
670
 *   @link http://tools.ietf.org/html/draft-reschke-http-status-308-07 draft for the new HTTP status codes: @endlink
671
 *   - 301: Moved Permanently (the recommended value for most redirects).
672
 *   - 302: Found (default in Drupal and PHP, sometimes used for spamming search
673
 *     engines).
674
 *   - 303: See Other.
675
 *   - 304: Not Modified.
676
 *   - 305: Use Proxy.
677
 *   - 307: Temporary Redirect.
678
 *
679
 * @see drupal_get_destination()
680
 * @see url()
681
 */
682
function drupal_goto($path = '', array $options = array(), $http_response_code = 302) {
683
  // A destination in $_GET always overrides the function arguments.
684
  // We do not allow absolute URLs to be passed via $_GET, as this can be an attack vector.
685
  if (isset($_GET['destination']) && !url_is_external($_GET['destination'])) {
686
    $destination = drupal_parse_url($_GET['destination']);
687
    $path = $destination['path'];
688
    $options['query'] = $destination['query'];
689
    $options['fragment'] = $destination['fragment'];
690
  }
691

    
692
  // In some cases modules call drupal_goto(current_path()). We need to ensure
693
  // that such a redirect is not to an external URL.
694
  if ($path === current_path() && empty($options['external']) && url_is_external($path)) {
695
    // Force url() to generate a non-external URL.
696
    $options['external'] = FALSE;
697
  }
698

    
699
  drupal_alter('drupal_goto', $path, $options, $http_response_code);
700

    
701
  // The 'Location' HTTP header must be absolute.
702
  $options['absolute'] = TRUE;
703

    
704
  $url = url($path, $options);
705

    
706
  header('Location: ' . $url, TRUE, $http_response_code);
707

    
708
  // The "Location" header sends a redirect status code to the HTTP daemon. In
709
  // some cases this can be wrong, so we make sure none of the code below the
710
  // drupal_goto() call gets executed upon redirection.
711
  drupal_exit($url);
712
}
713

    
714
/**
715
 * Delivers a "site is under maintenance" message to the browser.
716
 *
717
 * Page callback functions wanting to report a "site offline" message should
718
 * return MENU_SITE_OFFLINE instead of calling drupal_site_offline(). However,
719
 * functions that are invoked in contexts where that return value might not
720
 * bubble up to menu_execute_active_handler() should call drupal_site_offline().
721
 */
722
function drupal_site_offline() {
723
  drupal_deliver_page(MENU_SITE_OFFLINE);
724
}
725

    
726
/**
727
 * Delivers a "page not found" error to the browser.
728
 *
729
 * Page callback functions wanting to report a "page not found" message should
730
 * return MENU_NOT_FOUND instead of calling drupal_not_found(). However,
731
 * functions that are invoked in contexts where that return value might not
732
 * bubble up to menu_execute_active_handler() should call drupal_not_found().
733
 */
734
function drupal_not_found() {
735
  drupal_deliver_page(MENU_NOT_FOUND);
736
}
737

    
738
/**
739
 * Delivers an "access denied" error to the browser.
740
 *
741
 * Page callback functions wanting to report an "access denied" message should
742
 * return MENU_ACCESS_DENIED instead of calling drupal_access_denied(). However,
743
 * functions that are invoked in contexts where that return value might not
744
 * bubble up to menu_execute_active_handler() should call
745
 * drupal_access_denied().
746
 */
747
function drupal_access_denied() {
748
  drupal_deliver_page(MENU_ACCESS_DENIED);
749
}
750

    
751
/**
752
 * Performs an HTTP request.
753
 *
754
 * This is a flexible and powerful HTTP client implementation. Correctly
755
 * handles GET, POST, PUT or any other HTTP requests. Handles redirects.
756
 *
757
 * @param $url
758
 *   A string containing a fully qualified URI.
759
 * @param array $options
760
 *   (optional) An array that can have one or more of the following elements:
761
 *   - headers: An array containing request headers to send as name/value pairs.
762
 *   - method: A string containing the request method. Defaults to 'GET'.
763
 *   - data: A string containing the request body, formatted as
764
 *     'param=value&param=value&...'; to generate this, use http_build_query().
765
 *     Defaults to NULL.
766
 *   - max_redirects: An integer representing how many times a redirect
767
 *     may be followed. Defaults to 3.
768
 *   - timeout: A float representing the maximum number of seconds the function
769
 *     call may take. The default is 30 seconds. If a timeout occurs, the error
770
 *     code is set to the HTTP_REQUEST_TIMEOUT constant.
771
 *   - context: A context resource created with stream_context_create().
772
 *
773
 * @return object
774
 *   An object that can have one or more of the following components:
775
 *   - request: A string containing the request body that was sent.
776
 *   - code: An integer containing the response status code, or the error code
777
 *     if an error occurred.
778
 *   - protocol: The response protocol (e.g. HTTP/1.1 or HTTP/1.0).
779
 *   - status_message: The status message from the response, if a response was
780
 *     received.
781
 *   - redirect_code: If redirected, an integer containing the initial response
782
 *     status code.
783
 *   - redirect_url: If redirected, a string containing the URL of the redirect
784
 *     target.
785
 *   - error: If an error occurred, the error message. Otherwise not set.
786
 *   - headers: An array containing the response headers as name/value pairs.
787
 *     HTTP header names are case-insensitive (RFC 2616, section 4.2), so for
788
 *     easy access the array keys are returned in lower case.
789
 *   - data: A string containing the response body that was received.
790
 *
791
 * @see http_build_query()
792
 */
793
function drupal_http_request($url, array $options = array()) {
794
  // Allow an alternate HTTP client library to replace Drupal's default
795
  // implementation.
796
  $override_function = variable_get('drupal_http_request_function', FALSE);
797
  if (!empty($override_function) && function_exists($override_function)) {
798
    return $override_function($url, $options);
799
  }
800

    
801
  $result = new stdClass();
802

    
803
  // Parse the URL and make sure we can handle the schema.
804
  $uri = @parse_url($url);
805

    
806
  if ($uri == FALSE) {
807
    $result->error = 'unable to parse URL';
808
    $result->code = -1001;
809
    return $result;
810
  }
811

    
812
  if (!isset($uri['scheme'])) {
813
    $result->error = 'missing schema';
814
    $result->code = -1002;
815
    return $result;
816
  }
817

    
818
  timer_start(__FUNCTION__);
819

    
820
  // Merge the default options.
821
  $options += array(
822
    'headers' => array(),
823
    'method' => 'GET',
824
    'data' => NULL,
825
    'max_redirects' => 3,
826
    'timeout' => 30.0,
827
    'context' => NULL,
828
  );
829

    
830
  // Merge the default headers.
831
  $options['headers'] += array(
832
    'User-Agent' => 'Drupal (+http://drupal.org/)',
833
  );
834

    
835
  // stream_socket_client() requires timeout to be a float.
836
  $options['timeout'] = (float) $options['timeout'];
837

    
838
  // Use a proxy if one is defined and the host is not on the excluded list.
839
  $proxy_server = variable_get('proxy_server', '');
840
  if ($proxy_server && _drupal_http_use_proxy($uri['host'])) {
841
    // Set the scheme so we open a socket to the proxy server.
842
    $uri['scheme'] = 'proxy';
843
    // Set the path to be the full URL.
844
    $uri['path'] = $url;
845
    // Since the URL is passed as the path, we won't use the parsed query.
846
    unset($uri['query']);
847

    
848
    // Add in username and password to Proxy-Authorization header if needed.
849
    if ($proxy_username = variable_get('proxy_username', '')) {
850
      $proxy_password = variable_get('proxy_password', '');
851
      $options['headers']['Proxy-Authorization'] = 'Basic ' . base64_encode($proxy_username . (!empty($proxy_password) ? ":" . $proxy_password : ''));
852
    }
853
    // Some proxies reject requests with any User-Agent headers, while others
854
    // require a specific one.
855
    $proxy_user_agent = variable_get('proxy_user_agent', '');
856
    // The default value matches neither condition.
857
    if ($proxy_user_agent === NULL) {
858
      unset($options['headers']['User-Agent']);
859
    }
860
    elseif ($proxy_user_agent) {
861
      $options['headers']['User-Agent'] = $proxy_user_agent;
862
    }
863
  }
864

    
865
  switch ($uri['scheme']) {
866
    case 'proxy':
867
      // Make the socket connection to a proxy server.
868
      $socket = 'tcp://' . $proxy_server . ':' . variable_get('proxy_port', 8080);
869
      // The Host header still needs to match the real request.
870
      $options['headers']['Host'] = $uri['host'];
871
      $options['headers']['Host'] .= isset($uri['port']) && $uri['port'] != 80 ? ':' . $uri['port'] : '';
872
      break;
873

    
874
    case 'http':
875
    case 'feed':
876
      $port = isset($uri['port']) ? $uri['port'] : 80;
877
      $socket = 'tcp://' . $uri['host'] . ':' . $port;
878
      // RFC 2616: "non-standard ports MUST, default ports MAY be included".
879
      // We don't add the standard port to prevent from breaking rewrite rules
880
      // checking the host that do not take into account the port number.
881
      $options['headers']['Host'] = $uri['host'] . ($port != 80 ? ':' . $port : '');
882
      break;
883

    
884
    case 'https':
885
      // Note: Only works when PHP is compiled with OpenSSL support.
886
      $port = isset($uri['port']) ? $uri['port'] : 443;
887
      $socket = 'ssl://' . $uri['host'] . ':' . $port;
888
      $options['headers']['Host'] = $uri['host'] . ($port != 443 ? ':' . $port : '');
889
      break;
890

    
891
    default:
892
      $result->error = 'invalid schema ' . $uri['scheme'];
893
      $result->code = -1003;
894
      return $result;
895
  }
896

    
897
  if (empty($options['context'])) {
898
    $fp = @stream_socket_client($socket, $errno, $errstr, $options['timeout']);
899
  }
900
  else {
901
    // Create a stream with context. Allows verification of a SSL certificate.
902
    $fp = @stream_socket_client($socket, $errno, $errstr, $options['timeout'], STREAM_CLIENT_CONNECT, $options['context']);
903
  }
904

    
905
  // Make sure the socket opened properly.
906
  if (!$fp) {
907
    // When a network error occurs, we use a negative number so it does not
908
    // clash with the HTTP status codes.
909
    $result->code = -$errno;
910
    $result->error = trim($errstr) ? trim($errstr) : t('Error opening socket @socket', array('@socket' => $socket));
911

    
912
    // Mark that this request failed. This will trigger a check of the web
913
    // server's ability to make outgoing HTTP requests the next time that
914
    // requirements checking is performed.
915
    // See system_requirements().
916
    variable_set('drupal_http_request_fails', TRUE);
917

    
918
    return $result;
919
  }
920

    
921
  // Construct the path to act on.
922
  $path = isset($uri['path']) ? $uri['path'] : '/';
923
  if (isset($uri['query'])) {
924
    $path .= '?' . $uri['query'];
925
  }
926

    
927
  // Only add Content-Length if we actually have any content or if it is a POST
928
  // or PUT request. Some non-standard servers get confused by Content-Length in
929
  // at least HEAD/GET requests, and Squid always requires Content-Length in
930
  // POST/PUT requests.
931
  $content_length = strlen($options['data']);
932
  if ($content_length > 0 || $options['method'] == 'POST' || $options['method'] == 'PUT') {
933
    $options['headers']['Content-Length'] = $content_length;
934
  }
935

    
936
  // If the server URL has a user then attempt to use basic authentication.
937
  if (isset($uri['user'])) {
938
    $options['headers']['Authorization'] = 'Basic ' . base64_encode($uri['user'] . (isset($uri['pass']) ? ':' . $uri['pass'] : ':'));
939
  }
940

    
941
  // If the database prefix is being used by SimpleTest to run the tests in a copied
942
  // database then set the user-agent header to the database prefix so that any
943
  // calls to other Drupal pages will run the SimpleTest prefixed database. The
944
  // user-agent is used to ensure that multiple testing sessions running at the
945
  // same time won't interfere with each other as they would if the database
946
  // prefix were stored statically in a file or database variable.
947
  $test_info = &$GLOBALS['drupal_test_info'];
948
  if (!empty($test_info['test_run_id'])) {
949
    $options['headers']['User-Agent'] = drupal_generate_test_ua($test_info['test_run_id']);
950
  }
951

    
952
  $request = $options['method'] . ' ' . $path . " HTTP/1.0\r\n";
953
  foreach ($options['headers'] as $name => $value) {
954
    $request .= $name . ': ' . trim($value) . "\r\n";
955
  }
956
  $request .= "\r\n" . $options['data'];
957
  $result->request = $request;
958
  // Calculate how much time is left of the original timeout value.
959
  $timeout = $options['timeout'] - timer_read(__FUNCTION__) / 1000;
960
  if ($timeout > 0) {
961
    stream_set_timeout($fp, floor($timeout), floor(1000000 * fmod($timeout, 1)));
962
    fwrite($fp, $request);
963
  }
964

    
965
  // Fetch response. Due to PHP bugs like http://bugs.php.net/bug.php?id=43782
966
  // and http://bugs.php.net/bug.php?id=46049 we can't rely on feof(), but
967
  // instead must invoke stream_get_meta_data() each iteration.
968
  $info = stream_get_meta_data($fp);
969
  $alive = !$info['eof'] && !$info['timed_out'];
970
  $response = '';
971

    
972
  while ($alive) {
973
    // Calculate how much time is left of the original timeout value.
974
    $timeout = $options['timeout'] - timer_read(__FUNCTION__) / 1000;
975
    if ($timeout <= 0) {
976
      $info['timed_out'] = TRUE;
977
      break;
978
    }
979
    stream_set_timeout($fp, floor($timeout), floor(1000000 * fmod($timeout, 1)));
980
    $chunk = fread($fp, 1024);
981
    $response .= $chunk;
982
    $info = stream_get_meta_data($fp);
983
    $alive = !$info['eof'] && !$info['timed_out'] && $chunk;
984
  }
985
  fclose($fp);
986

    
987
  if ($info['timed_out']) {
988
    $result->code = HTTP_REQUEST_TIMEOUT;
989
    $result->error = 'request timed out';
990
    return $result;
991
  }
992
  // Parse response headers from the response body.
993
  // Be tolerant of malformed HTTP responses that separate header and body with
994
  // \n\n or \r\r instead of \r\n\r\n.
995
  list($response, $result->data) = preg_split("/\r\n\r\n|\n\n|\r\r/", $response, 2);
996
  $response = preg_split("/\r\n|\n|\r/", $response);
997

    
998
  // Parse the response status line.
999
  $response_status_array = _drupal_parse_response_status(trim(array_shift($response)));
1000
  $result->protocol = $response_status_array['http_version'];
1001
  $result->status_message = $response_status_array['reason_phrase'];
1002
  $code = $response_status_array['response_code'];
1003

    
1004
  $result->headers = array();
1005

    
1006
  // Parse the response headers.
1007
  while ($line = trim(array_shift($response))) {
1008
    list($name, $value) = explode(':', $line, 2);
1009
    $name = strtolower($name);
1010
    if (isset($result->headers[$name]) && $name == 'set-cookie') {
1011
      // RFC 2109: the Set-Cookie response header comprises the token Set-
1012
      // Cookie:, followed by a comma-separated list of one or more cookies.
1013
      $result->headers[$name] .= ',' . trim($value);
1014
    }
1015
    else {
1016
      $result->headers[$name] = trim($value);
1017
    }
1018
  }
1019

    
1020
  $responses = array(
1021
    100 => 'Continue',
1022
    101 => 'Switching Protocols',
1023
    200 => 'OK',
1024
    201 => 'Created',
1025
    202 => 'Accepted',
1026
    203 => 'Non-Authoritative Information',
1027
    204 => 'No Content',
1028
    205 => 'Reset Content',
1029
    206 => 'Partial Content',
1030
    300 => 'Multiple Choices',
1031
    301 => 'Moved Permanently',
1032
    302 => 'Found',
1033
    303 => 'See Other',
1034
    304 => 'Not Modified',
1035
    305 => 'Use Proxy',
1036
    307 => 'Temporary Redirect',
1037
    400 => 'Bad Request',
1038
    401 => 'Unauthorized',
1039
    402 => 'Payment Required',
1040
    403 => 'Forbidden',
1041
    404 => 'Not Found',
1042
    405 => 'Method Not Allowed',
1043
    406 => 'Not Acceptable',
1044
    407 => 'Proxy Authentication Required',
1045
    408 => 'Request Time-out',
1046
    409 => 'Conflict',
1047
    410 => 'Gone',
1048
    411 => 'Length Required',
1049
    412 => 'Precondition Failed',
1050
    413 => 'Request Entity Too Large',
1051
    414 => 'Request-URI Too Large',
1052
    415 => 'Unsupported Media Type',
1053
    416 => 'Requested range not satisfiable',
1054
    417 => 'Expectation Failed',
1055
    500 => 'Internal Server Error',
1056
    501 => 'Not Implemented',
1057
    502 => 'Bad Gateway',
1058
    503 => 'Service Unavailable',
1059
    504 => 'Gateway Time-out',
1060
    505 => 'HTTP Version not supported',
1061
  );
1062
  // RFC 2616 states that all unknown HTTP codes must be treated the same as the
1063
  // base code in their class.
1064
  if (!isset($responses[$code])) {
1065
    $code = floor($code / 100) * 100;
1066
  }
1067
  $result->code = $code;
1068

    
1069
  switch ($code) {
1070
    case 200: // OK
1071
    case 201: // Created
1072
    case 202: // Accepted
1073
    case 203: // Non-Authoritative Information
1074
    case 204: // No Content
1075
    case 205: // Reset Content
1076
    case 206: // Partial Content
1077
    case 304: // Not modified
1078
      break;
1079
    case 301: // Moved permanently
1080
    case 302: // Moved temporarily
1081
    case 307: // Moved temporarily
1082
      $location = $result->headers['location'];
1083
      $options['timeout'] -= timer_read(__FUNCTION__) / 1000;
1084
      if ($options['timeout'] <= 0) {
1085
        $result->code = HTTP_REQUEST_TIMEOUT;
1086
        $result->error = 'request timed out';
1087
      }
1088
      elseif ($options['max_redirects']) {
1089
        // Redirect to the new location.
1090
        $options['max_redirects']--;
1091
        $result = drupal_http_request($location, $options);
1092
        $result->redirect_code = $code;
1093
      }
1094
      if (!isset($result->redirect_url)) {
1095
        $result->redirect_url = $location;
1096
      }
1097
      break;
1098
    default:
1099
      $result->error = $result->status_message;
1100
  }
1101

    
1102
  return $result;
1103
}
1104

    
1105
/**
1106
 * Splits an HTTP response status line into components.
1107
 *
1108
 * See the @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html status line definition @endlink
1109
 * in RFC 2616.
1110
 *
1111
 * @param string $respone
1112
 *   The response status line, for example 'HTTP/1.1 500 Internal Server Error'.
1113
 *
1114
 * @return array
1115
 *   Keyed array containing the component parts. If the response is malformed,
1116
 *   all possible parts will be extracted. 'reason_phrase' could be empty.
1117
 *   Possible keys:
1118
 *   - 'http_version'
1119
 *   - 'response_code'
1120
 *   - 'reason_phrase'
1121
 */
1122
function _drupal_parse_response_status($response) {
1123
  $response_array = explode(' ', trim($response), 3);
1124
  // Set up empty values.
1125
  $result = array(
1126
    'reason_phrase' => '',
1127
  );
1128
  $result['http_version'] = $response_array[0];
1129
  $result['response_code'] = $response_array[1];
1130
  if (isset($response_array[2])) {
1131
    $result['reason_phrase'] = $response_array[2];
1132
  }
1133
  return $result;
1134
}
1135

    
1136
/**
1137
 * Helper function for determining hosts excluded from needing a proxy.
1138
 *
1139
 * @return
1140
 *   TRUE if a proxy should be used for this host.
1141
 */
1142
function _drupal_http_use_proxy($host) {
1143
  $proxy_exceptions = variable_get('proxy_exceptions', array('localhost', '127.0.0.1'));
1144
  return !in_array(strtolower($host), $proxy_exceptions, TRUE);
1145
}
1146

    
1147
/**
1148
 * @} End of "HTTP handling".
1149
 */
1150

    
1151
/**
1152
 * Strips slashes from a string or array of strings.
1153
 *
1154
 * Callback for array_walk() within fix_gpx_magic().
1155
 *
1156
 * @param $item
1157
 *   An individual string or array of strings from superglobals.
1158
 */
1159
function _fix_gpc_magic(&$item) {
1160
  if (is_array($item)) {
1161
    array_walk($item, '_fix_gpc_magic');
1162
  }
1163
  else {
1164
    $item = stripslashes($item);
1165
  }
1166
}
1167

    
1168
/**
1169
 * Strips slashes from $_FILES items.
1170
 *
1171
 * Callback for array_walk() within fix_gpc_magic().
1172
 *
1173
 * The tmp_name key is skipped keys since PHP generates single backslashes for
1174
 * file paths on Windows systems.
1175
 *
1176
 * @param $item
1177
 *   An item from $_FILES.
1178
 * @param $key
1179
 *   The key for the item within $_FILES.
1180
 *
1181
 * @see http://php.net/manual/features.file-upload.php#42280
1182
 */
1183
function _fix_gpc_magic_files(&$item, $key) {
1184
  if ($key != 'tmp_name') {
1185
    if (is_array($item)) {
1186
      array_walk($item, '_fix_gpc_magic_files');
1187
    }
1188
    else {
1189
      $item = stripslashes($item);
1190
    }
1191
  }
1192
}
1193

    
1194
/**
1195
 * Fixes double-escaping caused by "magic quotes" in some PHP installations.
1196
 *
1197
 * @see _fix_gpc_magic()
1198
 * @see _fix_gpc_magic_files()
1199
 */
1200
function fix_gpc_magic() {
1201
  static $fixed = FALSE;
1202
  if (!$fixed && ini_get('magic_quotes_gpc')) {
1203
    array_walk($_GET, '_fix_gpc_magic');
1204
    array_walk($_POST, '_fix_gpc_magic');
1205
    array_walk($_COOKIE, '_fix_gpc_magic');
1206
    array_walk($_REQUEST, '_fix_gpc_magic');
1207
    array_walk($_FILES, '_fix_gpc_magic_files');
1208
  }
1209
  $fixed = TRUE;
1210
}
1211

    
1212
/**
1213
 * @defgroup validation Input validation
1214
 * @{
1215
 * Functions to validate user input.
1216
 */
1217

    
1218
/**
1219
 * Verifies the syntax of the given e-mail address.
1220
 *
1221
 * This uses the
1222
 * @link http://php.net/manual/filter.filters.validate.php PHP e-mail validation filter. @endlink
1223
 *
1224
 * @param $mail
1225
 *   A string containing an e-mail address.
1226
 *
1227
 * @return
1228
 *   TRUE if the address is in a valid format.
1229
 */
1230
function valid_email_address($mail) {
1231
  return (bool)filter_var($mail, FILTER_VALIDATE_EMAIL);
1232
}
1233

    
1234
/**
1235
 * Verifies the syntax of the given URL.
1236
 *
1237
 * This function should only be used on actual URLs. It should not be used for
1238
 * Drupal menu paths, which can contain arbitrary characters.
1239
 * Valid values per RFC 3986.
1240
 * @param $url
1241
 *   The URL to verify.
1242
 * @param $absolute
1243
 *   Whether the URL is absolute (beginning with a scheme such as "http:").
1244
 *
1245
 * @return
1246
 *   TRUE if the URL is in a valid format.
1247
 */
1248
function valid_url($url, $absolute = FALSE) {
1249
  if ($absolute) {
1250
    return (bool)preg_match("
1251
      /^                                                      # Start at the beginning of the text
1252
      (?:ftp|https?|feed):\/\/                                # Look for ftp, http, https or feed schemes
1253
      (?:                                                     # Userinfo (optional) which is typically
1254
        (?:(?:[\w\.\-\+!$&'\(\)*\+,;=]|%[0-9a-f]{2})+:)*      # a username or a username and password
1255
        (?:[\w\.\-\+%!$&'\(\)*\+,;=]|%[0-9a-f]{2})+@          # combination
1256
      )?
1257
      (?:
1258
        (?:[a-z0-9\-\.]|%[0-9a-f]{2})+                        # A domain name or a IPv4 address
1259
        |(?:\[(?:[0-9a-f]{0,4}:)*(?:[0-9a-f]{0,4})\])         # or a well formed IPv6 address
1260
      )
1261
      (?::[0-9]+)?                                            # Server port number (optional)
1262
      (?:[\/|\?]
1263
        (?:[\w#!:\.\?\+=&@$'~*,;\/\(\)\[\]\-]|%[0-9a-f]{2})   # The path and query (optional)
1264
      *)?
1265
    $/xi", $url);
1266
  }
1267
  else {
1268
    return (bool)preg_match("/^(?:[\w#!:\.\?\+=&@$'~*,;\/\(\)\[\]\-]|%[0-9a-f]{2})+$/i", $url);
1269
  }
1270
}
1271

    
1272
/**
1273
 * @} End of "defgroup validation".
1274
 */
1275

    
1276
/**
1277
 * Registers an event for the current visitor to the flood control mechanism.
1278
 *
1279
 * @param $name
1280
 *   The name of an event.
1281
 * @param $window
1282
 *   Optional number of seconds before this event expires. Defaults to 3600 (1
1283
 *   hour). Typically uses the same value as the flood_is_allowed() $window
1284
 *   parameter. Expired events are purged on cron run to prevent the flood table
1285
 *   from growing indefinitely.
1286
 * @param $identifier
1287
 *   Optional identifier (defaults to the current user's IP address).
1288
 */
1289
function flood_register_event($name, $window = 3600, $identifier = NULL) {
1290
  if (!isset($identifier)) {
1291
    $identifier = ip_address();
1292
  }
1293
  db_insert('flood')
1294
    ->fields(array(
1295
      'event' => $name,
1296
      'identifier' => $identifier,
1297
      'timestamp' => REQUEST_TIME,
1298
      'expiration' => REQUEST_TIME + $window,
1299
    ))
1300
    ->execute();
1301
}
1302

    
1303
/**
1304
 * Makes the flood control mechanism forget an event for the current visitor.
1305
 *
1306
 * @param $name
1307
 *   The name of an event.
1308
 * @param $identifier
1309
 *   Optional identifier (defaults to the current user's IP address).
1310
 */
1311
function flood_clear_event($name, $identifier = NULL) {
1312
  if (!isset($identifier)) {
1313
    $identifier = ip_address();
1314
  }
1315
  db_delete('flood')
1316
    ->condition('event', $name)
1317
    ->condition('identifier', $identifier)
1318
    ->execute();
1319
}
1320

    
1321
/**
1322
 * Checks whether a user is allowed to proceed with the specified event.
1323
 *
1324
 * Events can have thresholds saying that each user can only do that event
1325
 * a certain number of times in a time window. This function verifies that the
1326
 * current user has not exceeded this threshold.
1327
 *
1328
 * @param $name
1329
 *   The unique name of the event.
1330
 * @param $threshold
1331
 *   The maximum number of times each user can do this event per time window.
1332
 * @param $window
1333
 *   Number of seconds in the time window for this event (default is 3600
1334
 *   seconds, or 1 hour).
1335
 * @param $identifier
1336
 *   Unique identifier of the current user. Defaults to their IP address.
1337
 *
1338
 * @return
1339
 *   TRUE if the user is allowed to proceed. FALSE if they have exceeded the
1340
 *   threshold and should not be allowed to proceed.
1341
 */
1342
function flood_is_allowed($name, $threshold, $window = 3600, $identifier = NULL) {
1343
  if (!isset($identifier)) {
1344
    $identifier = ip_address();
1345
  }
1346
  $number = db_query("SELECT COUNT(*) FROM {flood} WHERE event = :event AND identifier = :identifier AND timestamp > :timestamp", array(
1347
    ':event' => $name,
1348
    ':identifier' => $identifier,
1349
    ':timestamp' => REQUEST_TIME - $window))
1350
    ->fetchField();
1351
  return ($number < $threshold);
1352
}
1353

    
1354
/**
1355
 * @defgroup sanitization Sanitization functions
1356
 * @{
1357
 * Functions to sanitize values.
1358
 *
1359
 * See http://drupal.org/writing-secure-code for information
1360
 * on writing secure code.
1361
 */
1362

    
1363
/**
1364
 * Strips dangerous protocols (e.g. 'javascript:') from a URI.
1365
 *
1366
 * This function must be called for all URIs within user-entered input prior
1367
 * to being output to an HTML attribute value. It is often called as part of
1368
 * check_url() or filter_xss(), but those functions return an HTML-encoded
1369
 * string, so this function can be called independently when the output needs to
1370
 * be a plain-text string for passing to t(), l(), drupal_attributes(), or
1371
 * another function that will call check_plain() separately.
1372
 *
1373
 * @param $uri
1374
 *   A plain-text URI that might contain dangerous protocols.
1375
 *
1376
 * @return
1377
 *   A plain-text URI stripped of dangerous protocols. As with all plain-text
1378
 *   strings, this return value must not be output to an HTML page without
1379
 *   check_plain() being called on it. However, it can be passed to functions
1380
 *   expecting plain-text strings.
1381
 *
1382
 * @see check_url()
1383
 */
1384
function drupal_strip_dangerous_protocols($uri) {
1385
  static $allowed_protocols;
1386

    
1387
  if (!isset($allowed_protocols)) {
1388
    $allowed_protocols = array_flip(variable_get('filter_allowed_protocols', array('ftp', 'http', 'https', 'irc', 'mailto', 'news', 'nntp', 'rtsp', 'sftp', 'ssh', 'tel', 'telnet', 'webcal')));
1389
  }
1390

    
1391
  // Iteratively remove any invalid protocol found.
1392
  do {
1393
    $before = $uri;
1394
    $colonpos = strpos($uri, ':');
1395
    if ($colonpos > 0) {
1396
      // We found a colon, possibly a protocol. Verify.
1397
      $protocol = substr($uri, 0, $colonpos);
1398
      // If a colon is preceded by a slash, question mark or hash, it cannot
1399
      // possibly be part of the URL scheme. This must be a relative URL, which
1400
      // inherits the (safe) protocol of the base document.
1401
      if (preg_match('![/?#]!', $protocol)) {
1402
        break;
1403
      }
1404
      // Check if this is a disallowed protocol. Per RFC2616, section 3.2.3
1405
      // (URI Comparison) scheme comparison must be case-insensitive.
1406
      if (!isset($allowed_protocols[strtolower($protocol)])) {
1407
        $uri = substr($uri, $colonpos + 1);
1408
      }
1409
    }
1410
  } while ($before != $uri);
1411

    
1412
  return $uri;
1413
}
1414

    
1415
/**
1416
 * Strips dangerous protocols from a URI and encodes it for output to HTML.
1417
 *
1418
 * @param $uri
1419
 *   A plain-text URI that might contain dangerous protocols.
1420
 *
1421
 * @return
1422
 *   A URI stripped of dangerous protocols and encoded for output to an HTML
1423
 *   attribute value. Because it is already encoded, it should not be set as a
1424
 *   value within a $attributes array passed to drupal_attributes(), because
1425
 *   drupal_attributes() expects those values to be plain-text strings. To pass
1426
 *   a filtered URI to drupal_attributes(), call
1427
 *   drupal_strip_dangerous_protocols() instead.
1428
 *
1429
 * @see drupal_strip_dangerous_protocols()
1430
 */
1431
function check_url($uri) {
1432
  return check_plain(drupal_strip_dangerous_protocols($uri));
1433
}
1434

    
1435
/**
1436
 * Applies a very permissive XSS/HTML filter for admin-only use.
1437
 *
1438
 * Use only for fields where it is impractical to use the
1439
 * whole filter system, but where some (mainly inline) mark-up
1440
 * is desired (so check_plain() is not acceptable).
1441
 *
1442
 * Allows all tags that can be used inside an HTML body, save
1443
 * for scripts and styles.
1444
 */
1445
function filter_xss_admin($string) {
1446
  return filter_xss($string, array('a', 'abbr', 'acronym', 'address', 'article', 'aside', 'b', 'bdi', 'bdo', 'big', 'blockquote', 'br', 'caption', 'cite', 'code', 'col', 'colgroup', 'command', 'dd', 'del', 'details', 'dfn', 'div', 'dl', 'dt', 'em', 'figcaption', 'figure', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'i', 'img', 'ins', 'kbd', 'li', 'mark', 'menu', 'meter', 'nav', 'ol', 'output', 'p', 'pre', 'progress', 'q', 'rp', 'rt', 'ruby', 's', 'samp', 'section', 'small', 'span', 'strong', 'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'time', 'tr', 'tt', 'u', 'ul', 'var', 'wbr'));
1447
}
1448

    
1449
/**
1450
 * Filters HTML to prevent cross-site-scripting (XSS) vulnerabilities.
1451
 *
1452
 * Based on kses by Ulf Harnhammar, see http://sourceforge.net/projects/kses.
1453
 * For examples of various XSS attacks, see: http://ha.ckers.org/xss.html.
1454
 *
1455
 * This code does four things:
1456
 * - Removes characters and constructs that can trick browsers.
1457
 * - Makes sure all HTML entities are well-formed.
1458
 * - Makes sure all HTML tags and attributes are well-formed.
1459
 * - Makes sure no HTML tags contain URLs with a disallowed protocol (e.g.
1460
 *   javascript:).
1461
 *
1462
 * @param $string
1463
 *   The string with raw HTML in it. It will be stripped of everything that can
1464
 *   cause an XSS attack.
1465
 * @param $allowed_tags
1466
 *   An array of allowed tags.
1467
 *
1468
 * @return
1469
 *   An XSS safe version of $string, or an empty string if $string is not
1470
 *   valid UTF-8.
1471
 *
1472
 * @see drupal_validate_utf8()
1473
 */
1474
function filter_xss($string, $allowed_tags = array('a', 'em', 'strong', 'cite', 'blockquote', 'code', 'ul', 'ol', 'li', 'dl', 'dt', 'dd')) {
1475
  // Only operate on valid UTF-8 strings. This is necessary to prevent cross
1476
  // site scripting issues on Internet Explorer 6.
1477
  if (!drupal_validate_utf8($string)) {
1478
    return '';
1479
  }
1480
  // Store the text format.
1481
  _filter_xss_split($allowed_tags, TRUE);
1482
  // Remove NULL characters (ignored by some browsers).
1483
  $string = str_replace(chr(0), '', $string);
1484
  // Remove Netscape 4 JS entities.
1485
  $string = preg_replace('%&\s*\{[^}]*(\}\s*;?|$)%', '', $string);
1486

    
1487
  // Defuse all HTML entities.
1488
  $string = str_replace('&', '&amp;', $string);
1489
  // Change back only well-formed entities in our whitelist:
1490
  // Decimal numeric entities.
1491
  $string = preg_replace('/&amp;#([0-9]+;)/', '&#\1', $string);
1492
  // Hexadecimal numeric entities.
1493
  $string = preg_replace('/&amp;#[Xx]0*((?:[0-9A-Fa-f]{2})+;)/', '&#x\1', $string);
1494
  // Named entities.
1495
  $string = preg_replace('/&amp;([A-Za-z][A-Za-z0-9]*;)/', '&\1', $string);
1496

    
1497
  return preg_replace_callback('%
1498
    (
1499
    <(?=[^a-zA-Z!/])  # a lone <
1500
    |                 # or
1501
    <!--.*?-->        # a comment
1502
    |                 # or
1503
    <[^>]*(>|$)       # a string that starts with a <, up until the > or the end of the string
1504
    |                 # or
1505
    >                 # just a >
1506
    )%x', '_filter_xss_split', $string);
1507
}
1508

    
1509
/**
1510
 * Processes an HTML tag.
1511
 *
1512
 * @param $m
1513
 *   An array with various meaning depending on the value of $store.
1514
 *   If $store is TRUE then the array contains the allowed tags.
1515
 *   If $store is FALSE then the array has one element, the HTML tag to process.
1516
 * @param $store
1517
 *   Whether to store $m.
1518
 *
1519
 * @return
1520
 *   If the element isn't allowed, an empty string. Otherwise, the cleaned up
1521
 *   version of the HTML element.
1522
 */
1523
function _filter_xss_split($m, $store = FALSE) {
1524
  static $allowed_html;
1525

    
1526
  if ($store) {
1527
    $allowed_html = array_flip($m);
1528
    return;
1529
  }
1530

    
1531
  $string = $m[1];
1532

    
1533
  if (substr($string, 0, 1) != '<') {
1534
    // We matched a lone ">" character.
1535
    return '&gt;';
1536
  }
1537
  elseif (strlen($string) == 1) {
1538
    // We matched a lone "<" character.
1539
    return '&lt;';
1540
  }
1541

    
1542
  if (!preg_match('%^<\s*(/\s*)?([a-zA-Z0-9\-]+)([^>]*)>?|(<!--.*?-->)$%', $string, $matches)) {
1543
    // Seriously malformed.
1544
    return '';
1545
  }
1546

    
1547
  $slash = trim($matches[1]);
1548
  $elem = &$matches[2];
1549
  $attrlist = &$matches[3];
1550
  $comment = &$matches[4];
1551

    
1552
  if ($comment) {
1553
    $elem = '!--';
1554
  }
1555

    
1556
  if (!isset($allowed_html[strtolower($elem)])) {
1557
    // Disallowed HTML element.
1558
    return '';
1559
  }
1560

    
1561
  if ($comment) {
1562
    return $comment;
1563
  }
1564

    
1565
  if ($slash != '') {
1566
    return "</$elem>";
1567
  }
1568

    
1569
  // Is there a closing XHTML slash at the end of the attributes?
1570
  $attrlist = preg_replace('%(\s?)/\s*$%', '\1', $attrlist, -1, $count);
1571
  $xhtml_slash = $count ? ' /' : '';
1572

    
1573
  // Clean up attributes.
1574
  $attr2 = implode(' ', _filter_xss_attributes($attrlist));
1575
  $attr2 = preg_replace('/[<>]/', '', $attr2);
1576
  $attr2 = strlen($attr2) ? ' ' . $attr2 : '';
1577

    
1578
  return "<$elem$attr2$xhtml_slash>";
1579
}
1580

    
1581
/**
1582
 * Processes a string of HTML attributes.
1583
 *
1584
 * @return
1585
 *   Cleaned up version of the HTML attributes.
1586
 */
1587
function _filter_xss_attributes($attr) {
1588
  $attrarr = array();
1589
  $mode = 0;
1590
  $attrname = '';
1591

    
1592
  while (strlen($attr) != 0) {
1593
    // Was the last operation successful?
1594
    $working = 0;
1595

    
1596
    switch ($mode) {
1597
      case 0:
1598
        // Attribute name, href for instance.
1599
        if (preg_match('/^([-a-zA-Z]+)/', $attr, $match)) {
1600
          $attrname = strtolower($match[1]);
1601
          $skip = ($attrname == 'style' || substr($attrname, 0, 2) == 'on');
1602
          $working = $mode = 1;
1603
          $attr = preg_replace('/^[-a-zA-Z]+/', '', $attr);
1604
        }
1605
        break;
1606

    
1607
      case 1:
1608
        // Equals sign or valueless ("selected").
1609
        if (preg_match('/^\s*=\s*/', $attr)) {
1610
          $working = 1; $mode = 2;
1611
          $attr = preg_replace('/^\s*=\s*/', '', $attr);
1612
          break;
1613
        }
1614

    
1615
        if (preg_match('/^\s+/', $attr)) {
1616
          $working = 1; $mode = 0;
1617
          if (!$skip) {
1618
            $attrarr[] = $attrname;
1619
          }
1620
          $attr = preg_replace('/^\s+/', '', $attr);
1621
        }
1622
        break;
1623

    
1624
      case 2:
1625
        // Attribute value, a URL after href= for instance.
1626
        if (preg_match('/^"([^"]*)"(\s+|$)/', $attr, $match)) {
1627
          $thisval = filter_xss_bad_protocol($match[1]);
1628

    
1629
          if (!$skip) {
1630
            $attrarr[] = "$attrname=\"$thisval\"";
1631
          }
1632
          $working = 1;
1633
          $mode = 0;
1634
          $attr = preg_replace('/^"[^"]*"(\s+|$)/', '', $attr);
1635
          break;
1636
        }
1637

    
1638
        if (preg_match("/^'([^']*)'(\s+|$)/", $attr, $match)) {
1639
          $thisval = filter_xss_bad_protocol($match[1]);
1640

    
1641
          if (!$skip) {
1642
            $attrarr[] = "$attrname='$thisval'";
1643
          }
1644
          $working = 1; $mode = 0;
1645
          $attr = preg_replace("/^'[^']*'(\s+|$)/", '', $attr);
1646
          break;
1647
        }
1648

    
1649
        if (preg_match("%^([^\s\"']+)(\s+|$)%", $attr, $match)) {
1650
          $thisval = filter_xss_bad_protocol($match[1]);
1651

    
1652
          if (!$skip) {
1653
            $attrarr[] = "$attrname=\"$thisval\"";
1654
          }
1655
          $working = 1; $mode = 0;
1656
          $attr = preg_replace("%^[^\s\"']+(\s+|$)%", '', $attr);
1657
        }
1658
        break;
1659
    }
1660

    
1661
    if ($working == 0) {
1662
      // Not well formed; remove and try again.
1663
      $attr = preg_replace('/
1664
        ^
1665
        (
1666
        "[^"]*("|$)     # - a string that starts with a double quote, up until the next double quote or the end of the string
1667
        |               # or
1668
        \'[^\']*(\'|$)| # - a string that starts with a quote, up until the next quote or the end of the string
1669
        |               # or
1670
        \S              # - a non-whitespace character
1671
        )*              # any number of the above three
1672
        \s*             # any number of whitespaces
1673
        /x', '', $attr);
1674
      $mode = 0;
1675
    }
1676
  }
1677

    
1678
  // The attribute list ends with a valueless attribute like "selected".
1679
  if ($mode == 1 && !$skip) {
1680
    $attrarr[] = $attrname;
1681
  }
1682
  return $attrarr;
1683
}
1684

    
1685
/**
1686
 * Processes an HTML attribute value and strips dangerous protocols from URLs.
1687
 *
1688
 * @param $string
1689
 *   The string with the attribute value.
1690
 * @param $decode
1691
 *   (deprecated) Whether to decode entities in the $string. Set to FALSE if the
1692
 *   $string is in plain text, TRUE otherwise. Defaults to TRUE. This parameter
1693
 *   is deprecated and will be removed in Drupal 8. To process a plain-text URI,
1694
 *   call drupal_strip_dangerous_protocols() or check_url() instead.
1695
 *
1696
 * @return
1697
 *   Cleaned up and HTML-escaped version of $string.
1698
 */
1699
function filter_xss_bad_protocol($string, $decode = TRUE) {
1700
  // Get the plain text representation of the attribute value (i.e. its meaning).
1701
  // @todo Remove the $decode parameter in Drupal 8, and always assume an HTML
1702
  //   string that needs decoding.
1703
  if ($decode) {
1704
    if (!function_exists('decode_entities')) {
1705
      require_once DRUPAL_ROOT . '/includes/unicode.inc';
1706
    }
1707

    
1708
    $string = decode_entities($string);
1709
  }
1710
  return check_plain(drupal_strip_dangerous_protocols($string));
1711
}
1712

    
1713
/**
1714
 * @} End of "defgroup sanitization".
1715
 */
1716

    
1717
/**
1718
 * @defgroup format Formatting
1719
 * @{
1720
 * Functions to format numbers, strings, dates, etc.
1721
 */
1722

    
1723
/**
1724
 * Formats an RSS channel.
1725
 *
1726
 * Arbitrary elements may be added using the $args associative array.
1727
 */
1728
function format_rss_channel($title, $link, $description, $items, $langcode = NULL, $args = array()) {
1729
  global $language_content;
1730
  $langcode = $langcode ? $langcode : $language_content->language;
1731

    
1732
  $output = "<channel>\n";
1733
  $output .= ' <title>' . check_plain($title) . "</title>\n";
1734
  $output .= ' <link>' . check_url($link) . "</link>\n";
1735

    
1736
  // The RSS 2.0 "spec" doesn't indicate HTML can be used in the description.
1737
  // We strip all HTML tags, but need to prevent double encoding from properly
1738
  // escaped source data (such as &amp becoming &amp;amp;).
1739
  $output .= ' <description>' . check_plain(decode_entities(strip_tags($description))) . "</description>\n";
1740
  $output .= ' <language>' . check_plain($langcode) . "</language>\n";
1741
  $output .= format_xml_elements($args);
1742
  $output .= $items;
1743
  $output .= "</channel>\n";
1744

    
1745
  return $output;
1746
}
1747

    
1748
/**
1749
 * Formats a single RSS item.
1750
 *
1751
 * Arbitrary elements may be added using the $args associative array.
1752
 */
1753
function format_rss_item($title, $link, $description, $args = array()) {
1754
  $output = "<item>\n";
1755
  $output .= ' <title>' . check_plain($title) . "</title>\n";
1756
  $output .= ' <link>' . check_url($link) . "</link>\n";
1757
  $output .= ' <description>' . check_plain($description) . "</description>\n";
1758
  $output .= format_xml_elements($args);
1759
  $output .= "</item>\n";
1760

    
1761
  return $output;
1762
}
1763

    
1764
/**
1765
 * Formats XML elements.
1766
 *
1767
 * @param $array
1768
 *   An array where each item represents an element and is either a:
1769
 *   - (key => value) pair (<key>value</key>)
1770
 *   - Associative array with fields:
1771
 *     - 'key': element name
1772
 *     - 'value': element contents
1773
 *     - 'attributes': associative array of element attributes
1774
 *     - 'encoded': TRUE if 'value' is already encoded
1775
 *
1776
 * In both cases, 'value' can be a simple string, or it can be another array
1777
 * with the same format as $array itself for nesting.
1778
 *
1779
 * If 'encoded' is TRUE it is up to the caller to ensure that 'value' is either
1780
 * entity-encoded or CDATA-escaped. Using this option is not recommended when
1781
 * working with untrusted user input, since failing to escape the data
1782
 * correctly has security implications.
1783
 */
1784
function format_xml_elements($array) {
1785
  $output = '';
1786
  foreach ($array as $key => $value) {
1787
    if (is_numeric($key)) {
1788
      if ($value['key']) {
1789
        $output .= ' <' . $value['key'];
1790
        if (isset($value['attributes']) && is_array($value['attributes'])) {
1791
          $output .= drupal_attributes($value['attributes']);
1792
        }
1793

    
1794
        if (isset($value['value']) && $value['value'] != '') {
1795
          $output .= '>' . (is_array($value['value']) ? format_xml_elements($value['value']) : (!empty($value['encoded']) ? $value['value'] : check_plain($value['value']))) . '</' . $value['key'] . ">\n";
1796
        }
1797
        else {
1798
          $output .= " />\n";
1799
        }
1800
      }
1801
    }
1802
    else {
1803
      $output .= ' <' . $key . '>' . (is_array($value) ? format_xml_elements($value) : check_plain($value)) . "</$key>\n";
1804
    }
1805
  }
1806
  return $output;
1807
}
1808

    
1809
/**
1810
 * Formats a string containing a count of items.
1811
 *
1812
 * This function ensures that the string is pluralized correctly. Since t() is
1813
 * called by this function, make sure not to pass already-localized strings to
1814
 * it.
1815
 *
1816
 * For example:
1817
 * @code
1818
 *   $output = format_plural($node->comment_count, '1 comment', '@count comments');
1819
 * @endcode
1820
 *
1821
 * Example with additional replacements:
1822
 * @code
1823
 *   $output = format_plural($update_count,
1824
 *     'Changed the content type of 1 post from %old-type to %new-type.',
1825
 *     'Changed the content type of @count posts from %old-type to %new-type.',
1826
 *     array('%old-type' => $info->old_type, '%new-type' => $info->new_type));
1827
 * @endcode
1828
 *
1829
 * @param $count
1830
 *   The item count to display.
1831
 * @param $singular
1832
 *   The string for the singular case. Make sure it is clear this is singular,
1833
 *   to ease translation (e.g. use "1 new comment" instead of "1 new"). Do not
1834
 *   use @count in the singular string.
1835
 * @param $plural
1836
 *   The string for the plural case. Make sure it is clear this is plural, to
1837
 *   ease translation. Use @count in place of the item count, as in
1838
 *   "@count new comments".
1839
 * @param $args
1840
 *   An associative array of replacements to make after translation. Instances
1841
 *   of any key in this array are replaced with the corresponding value.
1842
 *   Based on the first character of the key, the value is escaped and/or
1843
 *   themed. See format_string(). Note that you do not need to include @count
1844
 *   in this array; this replacement is done automatically for the plural case.
1845
 * @param $options
1846
 *   An associative array of additional options. See t() for allowed keys.
1847
 *
1848
 * @return
1849
 *   A translated string.
1850
 *
1851
 * @see t()
1852
 * @see format_string()
1853
 */
1854
function format_plural($count, $singular, $plural, array $args = array(), array $options = array()) {
1855
  $args['@count'] = $count;
1856
  if ($count == 1) {
1857
    return t($singular, $args, $options);
1858
  }
1859

    
1860
  // Get the plural index through the gettext formula.
1861
  $index = (function_exists('locale_get_plural')) ? locale_get_plural($count, isset($options['langcode']) ? $options['langcode'] : NULL) : -1;
1862
  // If the index cannot be computed, use the plural as a fallback (which
1863
  // allows for most flexiblity with the replaceable @count value).
1864
  if ($index < 0) {
1865
    return t($plural, $args, $options);
1866
  }
1867
  else {
1868
    switch ($index) {
1869
      case "0":
1870
        return t($singular, $args, $options);
1871
      case "1":
1872
        return t($plural, $args, $options);
1873
      default:
1874
        unset($args['@count']);
1875
        $args['@count[' . $index . ']'] = $count;
1876
        return t(strtr($plural, array('@count' => '@count[' . $index . ']')), $args, $options);
1877
    }
1878
  }
1879
}
1880

    
1881
/**
1882
 * Parses a given byte count.
1883
 *
1884
 * @param $size
1885
 *   A size expressed as a number of bytes with optional SI or IEC binary unit
1886
 *   prefix (e.g. 2, 3K, 5MB, 10G, 6GiB, 8 bytes, 9mbytes).
1887
 *
1888
 * @return
1889
 *   An integer representation of the size in bytes.
1890
 */
1891
function parse_size($size) {
1892
  $unit = preg_replace('/[^bkmgtpezy]/i', '', $size); // Remove the non-unit characters from the size.
1893
  $size = preg_replace('/[^0-9\.]/', '', $size); // Remove the non-numeric characters from the size.
1894
  if ($unit) {
1895
    // Find the position of the unit in the ordered string which is the power of magnitude to multiply a kilobyte by.
1896
    return round($size * pow(DRUPAL_KILOBYTE, stripos('bkmgtpezy', $unit[0])));
1897
  }
1898
  else {
1899
    return round($size);
1900
  }
1901
}
1902

    
1903
/**
1904
 * Generates a string representation for the given byte count.
1905
 *
1906
 * @param $size
1907
 *   A size in bytes.
1908
 * @param $langcode
1909
 *   Optional language code to translate to a language other than what is used
1910
 *   to display the page.
1911
 *
1912
 * @return
1913
 *   A translated string representation of the size.
1914
 */
1915
function format_size($size, $langcode = NULL) {
1916
  if ($size < DRUPAL_KILOBYTE) {
1917
    return format_plural($size, '1 byte', '@count bytes', array(), array('langcode' => $langcode));
1918
  }
1919
  else {
1920
    $size = $size / DRUPAL_KILOBYTE; // Convert bytes to kilobytes.
1921
    $units = array(
1922
      t('@size KB', array(), array('langcode' => $langcode)),
1923
      t('@size MB', array(), array('langcode' => $langcode)),
1924
      t('@size GB', array(), array('langcode' => $langcode)),
1925
      t('@size TB', array(), array('langcode' => $langcode)),
1926
      t('@size PB', array(), array('langcode' => $langcode)),
1927
      t('@size EB', array(), array('langcode' => $langcode)),
1928
      t('@size ZB', array(), array('langcode' => $langcode)),
1929
      t('@size YB', array(), array('langcode' => $langcode)),
1930
    );
1931
    foreach ($units as $unit) {
1932
      if (round($size, 2) >= DRUPAL_KILOBYTE) {
1933
        $size = $size / DRUPAL_KILOBYTE;
1934
      }
1935
      else {
1936
        break;
1937
      }
1938
    }
1939
    return str_replace('@size', round($size, 2), $unit);
1940
  }
1941
}
1942

    
1943
/**
1944
 * Formats a time interval with the requested granularity.
1945
 *
1946
 * @param $interval
1947
 *   The length of the interval in seconds.
1948
 * @param $granularity
1949
 *   How many different units to display in the string.
1950
 * @param $langcode
1951
 *   Optional language code to translate to a language other than
1952
 *   what is used to display the page.
1953
 *
1954
 * @return
1955
 *   A translated string representation of the interval.
1956
 */
1957
function format_interval($interval, $granularity = 2, $langcode = NULL) {
1958
  $units = array(
1959
    '1 year|@count years' => 31536000,
1960
    '1 month|@count months' => 2592000,
1961
    '1 week|@count weeks' => 604800,
1962
    '1 day|@count days' => 86400,
1963
    '1 hour|@count hours' => 3600,
1964
    '1 min|@count min' => 60,
1965
    '1 sec|@count sec' => 1
1966
  );
1967
  $output = '';
1968
  foreach ($units as $key => $value) {
1969
    $key = explode('|', $key);
1970
    if ($interval >= $value) {
1971
      $output .= ($output ? ' ' : '') . format_plural(floor($interval / $value), $key[0], $key[1], array(), array('langcode' => $langcode));
1972
      $interval %= $value;
1973
      $granularity--;
1974
    }
1975

    
1976
    if ($granularity == 0) {
1977
      break;
1978
    }
1979
  }
1980
  return $output ? $output : t('0 sec', array(), array('langcode' => $langcode));
1981
}
1982

    
1983
/**
1984
 * Formats a date, using a date type or a custom date format string.
1985
 *
1986
 * @param $timestamp
1987
 *   A UNIX timestamp to format.
1988
 * @param $type
1989
 *   (optional) The format to use, one of:
1990
 *   - 'short', 'medium', or 'long' (the corresponding built-in date formats).
1991
 *   - The name of a date type defined by a module in hook_date_format_types(),
1992
 *     if it's been assigned a format.
1993
 *   - The machine name of an administrator-defined date format.
1994
 *   - 'custom', to use $format.
1995
 *   Defaults to 'medium'.
1996
 * @param $format
1997
 *   (optional) If $type is 'custom', a PHP date format string suitable for
1998
 *   input to date(). Use a backslash to escape ordinary text, so it does not
1999
 *   get interpreted as date format characters.
2000
 * @param $timezone
2001
 *   (optional) Time zone identifier, as described at
2002
 *   http://php.net/manual/timezones.php Defaults to the time zone used to
2003
 *   display the page.
2004
 * @param $langcode
2005
 *   (optional) Language code to translate to. Defaults to the language used to
2006
 *   display the page.
2007
 *
2008
 * @return
2009
 *   A translated date string in the requested format.
2010
 */
2011
function format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL) {
2012
  // Use the advanced drupal_static() pattern, since this is called very often.
2013
  static $drupal_static_fast;
2014
  if (!isset($drupal_static_fast)) {
2015
    $drupal_static_fast['timezones'] = &drupal_static(__FUNCTION__);
2016
  }
2017
  $timezones = &$drupal_static_fast['timezones'];
2018

    
2019
  if (!isset($timezone)) {
2020
    $timezone = date_default_timezone_get();
2021
  }
2022
  // Store DateTimeZone objects in an array rather than repeatedly
2023
  // constructing identical objects over the life of a request.
2024
  if (!isset($timezones[$timezone])) {
2025
    $timezones[$timezone] = timezone_open($timezone);
2026
  }
2027

    
2028
  // Use the default langcode if none is set.
2029
  global $language;
2030
  if (empty($langcode)) {
2031
    $langcode = isset($language->language) ? $language->language : 'en';
2032
  }
2033

    
2034
  switch ($type) {
2035
    case 'short':
2036
      $format = variable_get('date_format_short', 'm/d/Y - H:i');
2037
      break;
2038

    
2039
    case 'long':
2040
      $format = variable_get('date_format_long', 'l, F j, Y - H:i');
2041
      break;
2042

    
2043
    case 'custom':
2044
      // No change to format.
2045
      break;
2046

    
2047
    case 'medium':
2048
    default:
2049
      // Retrieve the format of the custom $type passed.
2050
      if ($type != 'medium') {
2051
        $format = variable_get('date_format_' . $type, '');
2052
      }
2053
      // Fall back to 'medium'.
2054
      if ($format === '') {
2055
        $format = variable_get('date_format_medium', 'D, m/d/Y - H:i');
2056
      }
2057
      break;
2058
  }
2059

    
2060
  // Create a DateTime object from the timestamp.
2061
  $date_time = date_create('@' . $timestamp);
2062
  // Set the time zone for the DateTime object.
2063
  date_timezone_set($date_time, $timezones[$timezone]);
2064

    
2065
  // Encode markers that should be translated. 'A' becomes '\xEF\AA\xFF'.
2066
  // xEF and xFF are invalid UTF-8 sequences, and we assume they are not in the
2067
  // input string.
2068
  // Paired backslashes are isolated to prevent errors in read-ahead evaluation.
2069
  // The read-ahead expression ensures that A matches, but not \A.
2070
  $format = preg_replace(array('/\\\\\\\\/', '/(?<!\\\\)([AaeDlMTF])/'), array("\xEF\\\\\\\\\xFF", "\xEF\\\\\$1\$1\xFF"), $format);
2071

    
2072
  // Call date_format().
2073
  $format = date_format($date_time, $format);
2074

    
2075
  // Pass the langcode to _format_date_callback().
2076
  _format_date_callback(NULL, $langcode);
2077

    
2078
  // Translate the marked sequences.
2079
  return preg_replace_callback('/\xEF([AaeDlMTF]?)(.*?)\xFF/', '_format_date_callback', $format);
2080
}
2081

    
2082
/**
2083
 * Returns an ISO8601 formatted date based on the given date.
2084
 *
2085
 * Callback for use within hook_rdf_mapping() implementations.
2086
 *
2087
 * @param $date
2088
 *   A UNIX timestamp.
2089
 *
2090
 * @return string
2091
 *   An ISO8601 formatted date.
2092
 */
2093
function date_iso8601($date) {
2094
  // The DATE_ISO8601 constant cannot be used here because it does not match
2095
  // date('c') and produces invalid RDF markup.
2096
  return date('c', $date);
2097
}
2098

    
2099
/**
2100
 * Translates a formatted date string.
2101
 *
2102
 * Callback for preg_replace_callback() within format_date().
2103
 */
2104
function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
2105
  // We cache translations to avoid redundant and rather costly calls to t().
2106
  static $cache, $langcode;
2107

    
2108
  if (!isset($matches)) {
2109
    $langcode = $new_langcode;
2110
    return;
2111
  }
2112

    
2113
  $code = $matches[1];
2114
  $string = $matches[2];
2115

    
2116
  if (!isset($cache[$langcode][$code][$string])) {
2117
    $options = array(
2118
      'langcode' => $langcode,
2119
    );
2120

    
2121
    if ($code == 'F') {
2122
      $options['context'] = 'Long month name';
2123
    }
2124

    
2125
    if ($code == '') {
2126
      $cache[$langcode][$code][$string] = $string;
2127
    }
2128
    else {
2129
      $cache[$langcode][$code][$string] = t($string, array(), $options);
2130
    }
2131
  }
2132
  return $cache[$langcode][$code][$string];
2133
}
2134

    
2135
/**
2136
 * Format a username.
2137
 *
2138
 * This is also the label callback implementation of
2139
 * callback_entity_info_label() for user_entity_info().
2140
 *
2141
 * By default, the passed-in object's 'name' property is used if it exists, or
2142
 * else, the site-defined value for the 'anonymous' variable. However, a module
2143
 * may override this by implementing hook_username_alter(&$name, $account).
2144
 *
2145
 * @see hook_username_alter()
2146
 *
2147
 * @param $account
2148
 *   The account object for the user whose name is to be formatted.
2149
 *
2150
 * @return
2151
 *   An unsanitized string with the username to display. The code receiving
2152
 *   this result must ensure that check_plain() is called on it before it is
2153
 *   printed to the page.
2154
 */
2155
function format_username($account) {
2156
  $name = !empty($account->name) ? $account->name : variable_get('anonymous', t('Anonymous'));
2157
  drupal_alter('username', $name, $account);
2158
  return $name;
2159
}
2160

    
2161
/**
2162
 * @} End of "defgroup format".
2163
 */
2164

    
2165
/**
2166
 * Generates an internal or external URL.
2167
 *
2168
 * When creating links in modules, consider whether l() could be a better
2169
 * alternative than url().
2170
 *
2171
 * @param $path
2172
 *   (optional) The internal path or external URL being linked to, such as
2173
 *   "node/34" or "http://example.com/foo". The default value is equivalent to
2174
 *   passing in '<front>'. A few notes:
2175
 *   - If you provide a full URL, it will be considered an external URL.
2176
 *   - If you provide only the path (e.g. "node/34"), it will be
2177
 *     considered an internal link. In this case, it should be a system URL,
2178
 *     and it will be replaced with the alias, if one exists. Additional query
2179
 *     arguments for internal paths must be supplied in $options['query'], not
2180
 *     included in $path.
2181
 *   - If you provide an internal path and $options['alias'] is set to TRUE, the
2182
 *     path is assumed already to be the correct path alias, and the alias is
2183
 *     not looked up.
2184
 *   - The special string '<front>' generates a link to the site's base URL.
2185
 *   - If your external URL contains a query (e.g. http://example.com/foo?a=b),
2186
 *     then you can either URL encode the query keys and values yourself and
2187
 *     include them in $path, or use $options['query'] to let this function
2188
 *     URL encode them.
2189
 * @param $options
2190
 *   (optional) An associative array of additional options, with the following
2191
 *   elements:
2192
 *   - 'query': An array of query key/value-pairs (without any URL-encoding) to
2193
 *     append to the URL.
2194
 *   - 'fragment': A fragment identifier (named anchor) to append to the URL.
2195
 *     Do not include the leading '#' character.
2196
 *   - 'absolute': Defaults to FALSE. Whether to force the output to be an
2197
 *     absolute link (beginning with http:). Useful for links that will be
2198
 *     displayed outside the site, such as in an RSS feed.
2199
 *   - 'alias': Defaults to FALSE. Whether the given path is a URL alias
2200
 *     already.
2201
 *   - 'external': Whether the given path is an external URL.
2202
 *   - 'language': An optional language object. If the path being linked to is
2203
 *     internal to the site, $options['language'] is used to look up the alias
2204
 *     for the URL. If $options['language'] is omitted, the global $language_url
2205
 *     will be used.
2206
 *   - 'https': Whether this URL should point to a secure location. If not
2207
 *     defined, the current scheme is used, so the user stays on HTTP or HTTPS
2208
 *     respectively. TRUE enforces HTTPS and FALSE enforces HTTP, but HTTPS can
2209
 *     only be enforced when the variable 'https' is set to TRUE.
2210
 *   - 'base_url': Only used internally, to modify the base URL when a language
2211
 *     dependent URL requires so.
2212
 *   - 'prefix': Only used internally, to modify the path when a language
2213
 *     dependent URL requires so.
2214
 *   - 'script': The script filename in Drupal's root directory to use when
2215
 *     clean URLs are disabled, such as 'index.php'. Defaults to an empty
2216
 *     string, as most modern web servers automatically find 'index.php'. If
2217
 *     clean URLs are disabled, the value of $path is appended as query
2218
 *     parameter 'q' to $options['script'] in the returned URL. When deploying
2219
 *     Drupal on a web server that cannot be configured to automatically find
2220
 *     index.php, then hook_url_outbound_alter() can be implemented to force
2221
 *     this value to 'index.php'.
2222
 *   - 'entity_type': The entity type of the object that called url(). Only
2223
 *     set if url() is invoked by entity_uri().
2224
 *   - 'entity': The entity object (such as a node) for which the URL is being
2225
 *     generated. Only set if url() is invoked by entity_uri().
2226
 *
2227
 * @return
2228
 *   A string containing a URL to the given path.
2229
 */
2230
function url($path = NULL, array $options = array()) {
2231
  // Merge in defaults.
2232
  $options += array(
2233
    'fragment' => '',
2234
    'query' => array(),
2235
    'absolute' => FALSE,
2236
    'alias' => FALSE,
2237
    'prefix' => ''
2238
  );
2239

    
2240
  // Determine whether this is an external link, but ensure that the current
2241
  // path is always treated as internal by default (to prevent external link
2242
  // injection vulnerabilities).
2243
  if (!isset($options['external'])) {
2244
    $options['external'] = $path === $_GET['q'] ? FALSE : url_is_external($path);
2245
  }
2246

    
2247
  // Preserve the original path before altering or aliasing.
2248
  $original_path = $path;
2249

    
2250
  // Allow other modules to alter the outbound URL and options.
2251
  drupal_alter('url_outbound', $path, $options, $original_path);
2252

    
2253
  if (isset($options['fragment']) && $options['fragment'] !== '') {
2254
    $options['fragment'] = '#' . $options['fragment'];
2255
  }
2256

    
2257
  if ($options['external']) {
2258
    // Split off the fragment.
2259
    if (strpos($path, '#') !== FALSE) {
2260
      list($path, $old_fragment) = explode('#', $path, 2);
2261
      // If $options contains no fragment, take it over from the path.
2262
      if (isset($old_fragment) && !$options['fragment']) {
2263
        $options['fragment'] = '#' . $old_fragment;
2264
      }
2265
    }
2266
    // Append the query.
2267
    if ($options['query']) {
2268
      $path .= (strpos($path, '?') !== FALSE ? '&' : '?') . drupal_http_build_query($options['query']);
2269
    }
2270
    if (isset($options['https']) && variable_get('https', FALSE)) {
2271
      if ($options['https'] === TRUE) {
2272
        $path = str_replace('http://', 'https://', $path);
2273
      }
2274
      elseif ($options['https'] === FALSE) {
2275
        $path = str_replace('https://', 'http://', $path);
2276
      }
2277
    }
2278
    // Reassemble.
2279
    return $path . $options['fragment'];
2280
  }
2281

    
2282
  // Strip leading slashes from internal paths to prevent them becoming external
2283
  // URLs without protocol. /example.com should not be turned into
2284
  // //example.com.
2285
  $path = ltrim($path, '/');
2286

    
2287
  global $base_url, $base_secure_url, $base_insecure_url;
2288

    
2289
  // The base_url might be rewritten from the language rewrite in domain mode.
2290
  if (!isset($options['base_url'])) {
2291
    if (isset($options['https']) && variable_get('https', FALSE)) {
2292
      if ($options['https'] === TRUE) {
2293
        $options['base_url'] = $base_secure_url;
2294
        $options['absolute'] = TRUE;
2295
      }
2296
      elseif ($options['https'] === FALSE) {
2297
        $options['base_url'] = $base_insecure_url;
2298
        $options['absolute'] = TRUE;
2299
      }
2300
    }
2301
    else {
2302
      $options['base_url'] = $base_url;
2303
    }
2304
  }
2305

    
2306
  // The special path '<front>' links to the default front page.
2307
  if ($path == '<front>') {
2308
    $path = '';
2309
  }
2310
  elseif (!empty($path) && !$options['alias']) {
2311
    $language = isset($options['language']) && isset($options['language']->language) ? $options['language']->language : '';
2312
    $alias = drupal_get_path_alias($original_path, $language);
2313
    if ($alias != $original_path) {
2314
      $path = $alias;
2315
    }
2316
  }
2317

    
2318
  $base = $options['absolute'] ? $options['base_url'] . '/' : base_path();
2319
  $prefix = empty($path) ? rtrim($options['prefix'], '/') : $options['prefix'];
2320

    
2321
  // With Clean URLs.
2322
  if (!empty($GLOBALS['conf']['clean_url'])) {
2323
    $path = drupal_encode_path($prefix . $path);
2324
    if ($options['query']) {
2325
      return $base . $path . '?' . drupal_http_build_query($options['query']) . $options['fragment'];
2326
    }
2327
    else {
2328
      return $base . $path . $options['fragment'];
2329
    }
2330
  }
2331
  // Without Clean URLs.
2332
  else {
2333
    $path = $prefix . $path;
2334
    $query = array();
2335
    if (!empty($path)) {
2336
      $query['q'] = $path;
2337
    }
2338
    if ($options['query']) {
2339
      // We do not use array_merge() here to prevent overriding $path via query
2340
      // parameters.
2341
      $query += $options['query'];
2342
    }
2343
    $query = $query ? ('?' . drupal_http_build_query($query)) : '';
2344
    $script = isset($options['script']) ? $options['script'] : '';
2345
    return $base . $script . $query . $options['fragment'];
2346
  }
2347
}
2348

    
2349
/**
2350
 * Returns TRUE if a path is external to Drupal (e.g. http://example.com).
2351
 *
2352
 * If a path cannot be assessed by Drupal's menu handler, then we must
2353
 * treat it as potentially insecure.
2354
 *
2355
 * @param $path
2356
 *   The internal path or external URL being linked to, such as "node/34" or
2357
 *   "http://example.com/foo".
2358
 *
2359
 * @return
2360
 *   Boolean TRUE or FALSE, where TRUE indicates an external path.
2361
 */
2362
function url_is_external($path) {
2363
  $colonpos = strpos($path, ':');
2364
  // Some browsers treat \ as / so normalize to forward slashes.
2365
  $path = str_replace('\\', '/', $path);
2366
  // If the path starts with 2 slashes then it is always considered an external
2367
  // URL without an explicit protocol part.
2368
  return (strpos($path, '//') === 0)
2369
    // Leading control characters may be ignored or mishandled by browsers, so
2370
    // assume such a path may lead to an external location. The \p{C} character
2371
    // class matches all UTF-8 control, unassigned, and private characters.
2372
    || (preg_match('/^\p{C}/u', $path) !== 0)
2373
    // Avoid calling drupal_strip_dangerous_protocols() if there is any slash
2374
    // (/), hash (#) or question_mark (?) before the colon (:) occurrence - if
2375
    // any - as this would clearly mean it is not a URL.
2376
    || ($colonpos !== FALSE
2377
      && !preg_match('![/?#]!', substr($path, 0, $colonpos))
2378
      && drupal_strip_dangerous_protocols($path) == $path);
2379
}
2380

    
2381
/**
2382
 * Formats an attribute string for an HTTP header.
2383
 *
2384
 * @param $attributes
2385
 *   An associative array of attributes such as 'rel'.
2386
 *
2387
 * @return
2388
 *   A ; separated string ready for insertion in a HTTP header. No escaping is
2389
 *   performed for HTML entities, so this string is not safe to be printed.
2390
 *
2391
 * @see drupal_add_http_header()
2392
 */
2393
function drupal_http_header_attributes(array $attributes = array()) {
2394
  foreach ($attributes as $attribute => &$data) {
2395
    if (is_array($data)) {
2396
      $data = implode(' ', $data);
2397
    }
2398
    $data = $attribute . '="' . $data . '"';
2399
  }
2400
  return $attributes ? ' ' . implode('; ', $attributes) : '';
2401
}
2402

    
2403
/**
2404
 * Converts an associative array to an XML/HTML tag attribute string.
2405
 *
2406
 * Each array key and its value will be formatted into an attribute string.
2407
 * If a value is itself an array, then its elements are concatenated to a single
2408
 * space-delimited string (for example, a class attribute with multiple values).
2409
 *
2410
 * Attribute values are sanitized by running them through check_plain().
2411
 * Attribute names are not automatically sanitized. When using user-supplied
2412
 * attribute names, it is strongly recommended to allow only white-listed names,
2413
 * since certain attributes carry security risks and can be abused.
2414
 *
2415
 * Examples of security aspects when using drupal_attributes:
2416
 * @code
2417
 *   // By running the value in the following statement through check_plain,
2418
 *   // the malicious script is neutralized.
2419
 *   drupal_attributes(array('title' => t('<script>steal_cookie();</script>')));
2420
 *
2421
 *   // The statement below demonstrates dangerous use of drupal_attributes, and
2422
 *   // will return an onmouseout attribute with JavaScript code that, when used
2423
 *   // as attribute in a tag, will cause users to be redirected to another site.
2424
 *   //
2425
 *   // In this case, the 'onmouseout' attribute should not be whitelisted --
2426
 *   // you don't want users to have the ability to add this attribute or others
2427
 *   // that take JavaScript commands.
2428
 *   drupal_attributes(array('onmouseout' => 'window.location="http://malicious.com/";')));
2429
 * @endcode
2430
 *
2431
 * @param $attributes
2432
 *   An associative array of key-value pairs to be converted to attributes.
2433
 *
2434
 * @return
2435
 *   A string ready for insertion in a tag (starts with a space).
2436
 *
2437
 * @ingroup sanitization
2438
 */
2439
function drupal_attributes(array $attributes = array()) {
2440
  foreach ($attributes as $attribute => &$data) {
2441
    $data = implode(' ', (array) $data);
2442
    $data = $attribute . '="' . check_plain($data) . '"';
2443
  }
2444
  return $attributes ? ' ' . implode(' ', $attributes) : '';
2445
}
2446

    
2447
/**
2448
 * Formats an internal or external URL link as an HTML anchor tag.
2449
 *
2450
 * This function correctly handles aliased paths and adds an 'active' class
2451
 * attribute to links that point to the current page (for theming), so all
2452
 * internal links output by modules should be generated by this function if
2453
 * possible.
2454
 *
2455
 * However, for links enclosed in translatable text you should use t() and
2456
 * embed the HTML anchor tag directly in the translated string. For example:
2457
 * @code
2458
 * t('Visit the <a href="@url">settings</a> page', array('@url' => url('admin')));
2459
 * @endcode
2460
 * This keeps the context of the link title ('settings' in the example) for
2461
 * translators.
2462
 *
2463
 * @param string $text
2464
 *   The translated link text for the anchor tag.
2465
 * @param string $path
2466
 *   The internal path or external URL being linked to, such as "node/34" or
2467
 *   "http://example.com/foo". After the url() function is called to construct
2468
 *   the URL from $path and $options, the resulting URL is passed through
2469
 *   check_plain() before it is inserted into the HTML anchor tag, to ensure
2470
 *   well-formed HTML. See url() for more information and notes.
2471
 * @param array $options
2472
 *   An associative array of additional options. Defaults to an empty array. It
2473
 *   may contain the following elements.
2474
 *   - 'attributes': An associative array of HTML attributes to apply to the
2475
 *     anchor tag. If element 'class' is included, it must be an array; 'title'
2476
 *     must be a string; other elements are more flexible, as they just need
2477
 *     to work in a call to drupal_attributes($options['attributes']).
2478
 *   - 'html' (default FALSE): Whether $text is HTML or just plain-text. For
2479
 *     example, to make an image tag into a link, this must be set to TRUE, or
2480
 *     you will see the escaped HTML image tag. $text is not sanitized if
2481
 *     'html' is TRUE. The calling function must ensure that $text is already
2482
 *     safe.
2483
 *   - 'language': An optional language object. If the path being linked to is
2484
 *     internal to the site, $options['language'] is used to determine whether
2485
 *     the link is "active", or pointing to the current page (the language as
2486
 *     well as the path must match). This element is also used by url().
2487
 *   - Additional $options elements used by the url() function.
2488
 *
2489
 * @return string
2490
 *   An HTML string containing a link to the given path.
2491
 *
2492
 * @see url()
2493
 */
2494
function l($text, $path, array $options = array()) {
2495
  global $language_url;
2496
  static $use_theme = NULL;
2497

    
2498
  // Merge in defaults.
2499
  $options += array(
2500
    'attributes' => array(),
2501
    'html' => FALSE,
2502
  );
2503

    
2504
  // Append active class.
2505
  if (($path == $_GET['q'] || ($path == '<front>' && drupal_is_front_page())) &&
2506
      (empty($options['language']) || $options['language']->language == $language_url->language)) {
2507
    $options['attributes']['class'][] = 'active';
2508
  }
2509

    
2510
  // Remove all HTML and PHP tags from a tooltip. For best performance, we act only
2511
  // if a quick strpos() pre-check gave a suspicion (because strip_tags() is expensive).
2512
  if (isset($options['attributes']['title']) && strpos($options['attributes']['title'], '<') !== FALSE) {
2513
    $options['attributes']['title'] = strip_tags($options['attributes']['title']);
2514
  }
2515

    
2516
  // Determine if rendering of the link is to be done with a theme function
2517
  // or the inline default. Inline is faster, but if the theme system has been
2518
  // loaded and a module or theme implements a preprocess or process function
2519
  // or overrides the theme_link() function, then invoke theme(). Preliminary
2520
  // benchmarks indicate that invoking theme() can slow down the l() function
2521
  // by 20% or more, and that some of the link-heavy Drupal pages spend more
2522
  // than 10% of the total page request time in the l() function.
2523
  if (!isset($use_theme) && function_exists('theme')) {
2524
    // Allow edge cases to prevent theme initialization and force inline link
2525
    // rendering.
2526
    if (variable_get('theme_link', TRUE)) {
2527
      drupal_theme_initialize();
2528
      $registry = theme_get_registry(FALSE);
2529
      // We don't want to duplicate functionality that's in theme(), so any
2530
      // hint of a module or theme doing anything at all special with the 'link'
2531
      // theme hook should simply result in theme() being called. This includes
2532
      // the overriding of theme_link() with an alternate function or template,
2533
      // the presence of preprocess or process functions, or the presence of
2534
      // include files.
2535
      $use_theme = !isset($registry['link']['function']) || ($registry['link']['function'] != 'theme_link');
2536
      $use_theme = $use_theme || !empty($registry['link']['preprocess functions']) || !empty($registry['link']['process functions']) || !empty($registry['link']['includes']);
2537
    }
2538
    else {
2539
      $use_theme = FALSE;
2540
    }
2541
  }
2542
  if ($use_theme) {
2543
    return theme('link', array('text' => $text, 'path' => $path, 'options' => $options));
2544
  }
2545
  // The result of url() is a plain-text URL. Because we are using it here
2546
  // in an HTML argument context, we need to encode it properly.
2547
  return '<a href="' . check_plain(url($path, $options)) . '"' . drupal_attributes($options['attributes']) . '>' . ($options['html'] ? $text : check_plain($text)) . '</a>';
2548
}
2549

    
2550
/**
2551
 * Delivers a page callback result to the browser in the appropriate format.
2552
 *
2553
 * This function is most commonly called by menu_execute_active_handler(), but
2554
 * can also be called by error conditions such as drupal_not_found(),
2555
 * drupal_access_denied(), and drupal_site_offline().
2556
 *
2557
 * When a user requests a page, index.php calls menu_execute_active_handler(),
2558
 * which calls the 'page callback' function registered in hook_menu(). The page
2559
 * callback function can return one of:
2560
 * - NULL: to indicate no content.
2561
 * - An integer menu status constant: to indicate an error condition.
2562
 * - A string of HTML content.
2563
 * - A renderable array of content.
2564
 * Returning a renderable array rather than a string of HTML is preferred,
2565
 * because that provides modules with more flexibility in customizing the final
2566
 * result.
2567
 *
2568
 * When the page callback returns its constructed content to
2569
 * menu_execute_active_handler(), this function gets called. The purpose of
2570
 * this function is to determine the most appropriate 'delivery callback'
2571
 * function to route the content to. The delivery callback function then
2572
 * sends the content to the browser in the needed format. The default delivery
2573
 * callback is drupal_deliver_html_page(), which delivers the content as an HTML
2574
 * page, complete with blocks in addition to the content. This default can be
2575
 * overridden on a per menu router item basis by setting 'delivery callback' in
2576
 * hook_menu() or hook_menu_alter(), and can also be overridden on a per request
2577
 * basis in hook_page_delivery_callback_alter().
2578
 *
2579
 * For example, the same page callback function can be used for an HTML
2580
 * version of the page and an Ajax version of the page. The page callback
2581
 * function just needs to decide what content is to be returned and the
2582
 * delivery callback function will send it as an HTML page or an Ajax
2583
 * response, as appropriate.
2584
 *
2585
 * In order for page callbacks to be reusable in different delivery formats,
2586
 * they should not issue any "print" or "echo" statements, but instead just
2587
 * return content.
2588
 *
2589
 * Also note that this function does not perform access checks. The delivery
2590
 * callback function specified in hook_menu(), hook_menu_alter(), or
2591
 * hook_page_delivery_callback_alter() will be called even if the router item
2592
 * access checks fail. This is intentional (it is needed for JSON and other
2593
 * purposes), but it has security implications. Do not call this function
2594
 * directly unless you understand the security implications, and be careful in
2595
 * writing delivery callbacks, so that they do not violate security. See
2596
 * drupal_deliver_html_page() for an example of a delivery callback that
2597
 * respects security.
2598
 *
2599
 * @param $page_callback_result
2600
 *   The result of a page callback. Can be one of:
2601
 *   - NULL: to indicate no content.
2602
 *   - An integer menu status constant: to indicate an error condition.
2603
 *   - A string of HTML content.
2604
 *   - A renderable array of content.
2605
 * @param $default_delivery_callback
2606
 *   (Optional) If given, it is the name of a delivery function most likely
2607
 *   to be appropriate for the page request as determined by the calling
2608
 *   function (e.g., menu_execute_active_handler()). If not given, it is
2609
 *   determined from the menu router information of the current page.
2610
 *
2611
 * @see menu_execute_active_handler()
2612
 * @see hook_menu()
2613
 * @see hook_menu_alter()
2614
 * @see hook_page_delivery_callback_alter()
2615
 */
2616
function drupal_deliver_page($page_callback_result, $default_delivery_callback = NULL) {
2617
  if (!isset($default_delivery_callback) && ($router_item = menu_get_item())) {
2618
    $default_delivery_callback = $router_item['delivery_callback'];
2619
  }
2620
  $delivery_callback = !empty($default_delivery_callback) ? $default_delivery_callback : 'drupal_deliver_html_page';
2621
  // Give modules a chance to alter the delivery callback used, based on
2622
  // request-time context (e.g., HTTP request headers).
2623
  drupal_alter('page_delivery_callback', $delivery_callback);
2624
  if (function_exists($delivery_callback)) {
2625
    $delivery_callback($page_callback_result);
2626
  }
2627
  else {
2628
    // If a delivery callback is specified, but doesn't exist as a function,
2629
    // something is wrong, but don't print anything, since it's not known
2630
    // what format the response needs to be in.
2631
    watchdog('delivery callback not found', 'callback %callback not found: %q.', array('%callback' => $delivery_callback, '%q' => $_GET['q']), WATCHDOG_ERROR);
2632
  }
2633
}
2634

    
2635
/**
2636
 * Packages and sends the result of a page callback to the browser as HTML.
2637
 *
2638
 * @param $page_callback_result
2639
 *   The result of a page callback. Can be one of:
2640
 *   - NULL: to indicate no content.
2641
 *   - An integer menu status constant: to indicate an error condition.
2642
 *   - A string of HTML content.
2643
 *   - A renderable array of content.
2644
 *
2645
 * @see drupal_deliver_page()
2646
 */
2647
function drupal_deliver_html_page($page_callback_result) {
2648
  // Emit the correct charset HTTP header, but not if the page callback
2649
  // result is NULL, since that likely indicates that it printed something
2650
  // in which case, no further headers may be sent, and not if code running
2651
  // for this page request has already set the content type header.
2652
  if (isset($page_callback_result) && is_null(drupal_get_http_header('Content-Type'))) {
2653
    drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');
2654
  }
2655

    
2656
  // Send appropriate HTTP-Header for browsers and search engines.
2657
  global $language;
2658
  drupal_add_http_header('Content-Language', $language->language);
2659

    
2660
  // By default, do not allow the site to be rendered in an iframe on another
2661
  // domain, but provide a variable to override this. If the code running for
2662
  // this page request already set the X-Frame-Options header earlier, don't
2663
  // overwrite it here.
2664
  $frame_options = variable_get('x_frame_options', 'SAMEORIGIN');
2665
  if ($frame_options && is_null(drupal_get_http_header('X-Frame-Options'))) {
2666
    drupal_add_http_header('X-Frame-Options', $frame_options);
2667
  }
2668

    
2669
  // Menu status constants are integers; page content is a string or array.
2670
  if (is_int($page_callback_result)) {
2671
    // @todo: Break these up into separate functions?
2672
    switch ($page_callback_result) {
2673
      case MENU_NOT_FOUND:
2674
        // Print a 404 page.
2675
        drupal_add_http_header('Status', '404 Not Found');
2676

    
2677
        watchdog('page not found', check_plain($_GET['q']), NULL, WATCHDOG_WARNING);
2678

    
2679
        // Check for and return a fast 404 page if configured.
2680
        drupal_fast_404();
2681

    
2682
        // Keep old path for reference, and to allow forms to redirect to it.
2683
        if (!isset($_GET['destination'])) {
2684
          // Make sure that the current path is not interpreted as external URL.
2685
          if (!url_is_external($_GET['q'])) {
2686
            $_GET['destination'] = $_GET['q'];
2687
          }
2688
        }
2689

    
2690
        $path = drupal_get_normal_path(variable_get('site_404', ''));
2691
        if ($path && $path != $_GET['q']) {
2692
          // Custom 404 handler. Set the active item in case there are tabs to
2693
          // display, or other dependencies on the path.
2694
          menu_set_active_item($path);
2695
          $return = menu_execute_active_handler($path, FALSE);
2696
        }
2697

    
2698
        if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {
2699
          // Standard 404 handler.
2700
          drupal_set_title(t('Page not found'));
2701
          $return = t('The requested page "@path" could not be found.', array('@path' => request_uri()));
2702
        }
2703

    
2704
        drupal_set_page_content($return);
2705
        $page = element_info('page');
2706
        print drupal_render_page($page);
2707
        break;
2708

    
2709
      case MENU_ACCESS_DENIED:
2710
        // Print a 403 page.
2711
        drupal_add_http_header('Status', '403 Forbidden');
2712
        watchdog('access denied', check_plain($_GET['q']), NULL, WATCHDOG_WARNING);
2713

    
2714
        // Keep old path for reference, and to allow forms to redirect to it.
2715
        if (!isset($_GET['destination'])) {
2716
          // Make sure that the current path is not interpreted as external URL.
2717
          if (!url_is_external($_GET['q'])) {
2718
            $_GET['destination'] = $_GET['q'];
2719
          }
2720
        }
2721

    
2722
        $path = drupal_get_normal_path(variable_get('site_403', ''));
2723
        if ($path && $path != $_GET['q']) {
2724
          // Custom 403 handler. Set the active item in case there are tabs to
2725
          // display or other dependencies on the path.
2726
          menu_set_active_item($path);
2727
          $return = menu_execute_active_handler($path, FALSE);
2728
        }
2729

    
2730
        if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {
2731
          // Standard 403 handler.
2732
          drupal_set_title(t('Access denied'));
2733
          $return = t('You are not authorized to access this page.');
2734
        }
2735

    
2736
        print drupal_render_page($return);
2737
        break;
2738

    
2739
      case MENU_SITE_OFFLINE:
2740
        // Print a 503 page.
2741
        drupal_maintenance_theme();
2742
        drupal_add_http_header('Status', '503 Service unavailable');
2743
        drupal_set_title(t('Site under maintenance'));
2744
        print theme('maintenance_page', array('content' => filter_xss_admin(variable_get('maintenance_mode_message',
2745
          t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal')))))));
2746
        break;
2747
    }
2748
  }
2749
  elseif (isset($page_callback_result)) {
2750
    // Print anything besides a menu constant, assuming it's not NULL or
2751
    // undefined.
2752
    print drupal_render_page($page_callback_result);
2753
  }
2754

    
2755
  // Perform end-of-request tasks.
2756
  drupal_page_footer();
2757
}
2758

    
2759
/**
2760
 * Performs end-of-request tasks.
2761
 *
2762
 * This function sets the page cache if appropriate, and allows modules to
2763
 * react to the closing of the page by calling hook_exit().
2764
 */
2765
function drupal_page_footer() {
2766
  global $user;
2767

    
2768
  module_invoke_all('exit');
2769

    
2770
  // Commit the user session, if needed.
2771
  drupal_session_commit();
2772

    
2773
  if (variable_get('cache', 0) && ($cache = drupal_page_set_cache())) {
2774
    drupal_serve_page_from_cache($cache);
2775
  }
2776
  else {
2777
    ob_flush();
2778
  }
2779

    
2780
  _registry_check_code(REGISTRY_WRITE_LOOKUP_CACHE);
2781
  drupal_cache_system_paths();
2782
  module_implements_write_cache();
2783
  drupal_file_scan_write_cache();
2784
  system_run_automated_cron();
2785
}
2786

    
2787
/**
2788
 * Performs end-of-request tasks.
2789
 *
2790
 * In some cases page requests need to end without calling drupal_page_footer().
2791
 * In these cases, call drupal_exit() instead. There should rarely be a reason
2792
 * to call exit instead of drupal_exit();
2793
 *
2794
 * @param $destination
2795
 *   If this function is called from drupal_goto(), then this argument
2796
 *   will be a fully-qualified URL that is the destination of the redirect.
2797
 *   This should be passed along to hook_exit() implementations.
2798
 */
2799
function drupal_exit($destination = NULL) {
2800
  if (drupal_get_bootstrap_phase() == DRUPAL_BOOTSTRAP_FULL) {
2801
    if (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update') {
2802
      module_invoke_all('exit', $destination);
2803
    }
2804
    drupal_session_commit();
2805
  }
2806
  exit;
2807
}
2808

    
2809
/**
2810
 * Forms an associative array from a linear array.
2811
 *
2812
 * This function walks through the provided array and constructs an associative
2813
 * array out of it. The keys of the resulting array will be the values of the
2814
 * input array. The values will be the same as the keys unless a function is
2815
 * specified, in which case the output of the function is used for the values
2816
 * instead.
2817
 *
2818
 * @param $array
2819
 *   A linear array.
2820
 * @param $function
2821
 *   A name of a function to apply to all values before output.
2822
 *
2823
 * @return
2824
 *   An associative array.
2825
 */
2826
function drupal_map_assoc($array, $function = NULL) {
2827
  // array_combine() fails with empty arrays:
2828
  // http://bugs.php.net/bug.php?id=34857.
2829
  $array = !empty($array) ? array_combine($array, $array) : array();
2830
  if (is_callable($function)) {
2831
    $array = array_map($function, $array);
2832
  }
2833
  return $array;
2834
}
2835

    
2836
/**
2837
 * Attempts to set the PHP maximum execution time.
2838
 *
2839
 * This function is a wrapper around the PHP function set_time_limit().
2840
 * When called, set_time_limit() restarts the timeout counter from zero.
2841
 * In other words, if the timeout is the default 30 seconds, and 25 seconds
2842
 * into script execution a call such as set_time_limit(20) is made, the
2843
 * script will run for a total of 45 seconds before timing out.
2844
 *
2845
 * If the current time limit is not unlimited it is possible to decrease the
2846
 * total time limit if the sum of the new time limit and the current time spent
2847
 * running the script is inferior to the original time limit. It is inherent to
2848
 * the way set_time_limit() works, it should rather be called with an
2849
 * appropriate value every time you need to allocate a certain amount of time
2850
 * to execute a task than only once at the beginning of the script.
2851
 *
2852
 * Before calling set_time_limit(), we check if this function is available
2853
 * because it could be disabled by the server administrator. We also hide all
2854
 * the errors that could occur when calling set_time_limit(), because it is
2855
 * not possible to reliably ensure that PHP or a security extension will
2856
 * not issue a warning/error if they prevent the use of this function.
2857
 *
2858
 * @param $time_limit
2859
 *   An integer specifying the new time limit, in seconds. A value of 0
2860
 *   indicates unlimited execution time.
2861
 *
2862
 * @ingroup php_wrappers
2863
 */
2864
function drupal_set_time_limit($time_limit) {
2865
  if (function_exists('set_time_limit')) {
2866
    $current = ini_get('max_execution_time');
2867
    // Do not set time limit if it is currently unlimited.
2868
    if ($current != 0) {
2869
      @set_time_limit($time_limit);
2870
    }
2871
  }
2872
}
2873

    
2874
/**
2875
 * Returns the path to a system item (module, theme, etc.).
2876
 *
2877
 * @param $type
2878
 *   The type of the item (i.e. theme, theme_engine, module, profile).
2879
 * @param $name
2880
 *   The name of the item for which the path is requested.
2881
 *
2882
 * @return
2883
 *   The path to the requested item or an empty string if the item is not found.
2884
 */
2885
function drupal_get_path($type, $name) {
2886
  return dirname(drupal_get_filename($type, $name));
2887
}
2888

    
2889
/**
2890
 * Returns the base URL path (i.e., directory) of the Drupal installation.
2891
 *
2892
 * base_path() adds a "/" to the beginning and end of the returned path if the
2893
 * path is not empty. At the very least, this will return "/".
2894
 *
2895
 * Examples:
2896
 * - http://example.com returns "/" because the path is empty.
2897
 * - http://example.com/drupal/folder returns "/drupal/folder/".
2898
 */
2899
function base_path() {
2900
  return $GLOBALS['base_path'];
2901
}
2902

    
2903
/**
2904
 * Adds a LINK tag with a distinct 'rel' attribute to the page's HEAD.
2905
 *
2906
 * This function can be called as long the HTML header hasn't been sent, which
2907
 * on normal pages is up through the preprocess step of theme('html'). Adding
2908
 * a link will overwrite a prior link with the exact same 'rel' and 'href'
2909
 * attributes.
2910
 *
2911
 * @param $attributes
2912
 *   Associative array of element attributes including 'href' and 'rel'.
2913
 * @param $header
2914
 *   Optional flag to determine if a HTTP 'Link:' header should be sent.
2915
 */
2916
function drupal_add_html_head_link($attributes, $header = FALSE) {
2917
  $element = array(
2918
    '#tag' => 'link',
2919
    '#attributes' => $attributes,
2920
  );
2921
  $href = $attributes['href'];
2922

    
2923
  if ($header) {
2924
    // Also add a HTTP header "Link:".
2925
    $href = '<' . check_plain($attributes['href']) . '>;';
2926
    unset($attributes['href']);
2927
    $element['#attached']['drupal_add_http_header'][] = array('Link',  $href . drupal_http_header_attributes($attributes), TRUE);
2928
  }
2929

    
2930
  drupal_add_html_head($element, 'drupal_add_html_head_link:' . $attributes['rel'] . ':' . $href);
2931
}
2932

    
2933
/**
2934
 * Adds a cascading stylesheet to the stylesheet queue.
2935
 *
2936
 * Calling drupal_static_reset('drupal_add_css') will clear all cascading
2937
 * stylesheets added so far.
2938
 *
2939
 * If CSS aggregation/compression is enabled, all cascading style sheets added
2940
 * with $options['preprocess'] set to TRUE will be merged into one aggregate
2941
 * file and compressed by removing all extraneous white space.
2942
 * Preprocessed inline stylesheets will not be aggregated into this single file;
2943
 * instead, they are just compressed upon output on the page. Externally hosted
2944
 * stylesheets are never aggregated or compressed.
2945
 *
2946
 * The reason for aggregating the files is outlined quite thoroughly here:
2947
 * http://www.die.net/musings/page_load_time/ "Load fewer external objects. Due
2948
 * to request overhead, one bigger file just loads faster than two smaller ones
2949
 * half its size."
2950
 *
2951
 * $options['preprocess'] should be only set to TRUE when a file is required for
2952
 * all typical visitors and most pages of a site. It is critical that all
2953
 * preprocessed files are added unconditionally on every page, even if the
2954
 * files do not happen to be needed on a page. This is normally done by calling
2955
 * drupal_add_css() in a hook_init() implementation.
2956
 *
2957
 * Non-preprocessed files should only be added to the page when they are
2958
 * actually needed.
2959
 *
2960
 * @param $data
2961
 *   (optional) The stylesheet data to be added, depending on what is passed
2962
 *   through to the $options['type'] parameter:
2963
 *   - 'file': The path to the CSS file relative to the base_path(), or a
2964
 *     stream wrapper URI. For example: "modules/devel/devel.css" or
2965
 *     "public://generated_css/stylesheet_1.css". Note that Modules should
2966
 *     always prefix the names of their CSS files with the module name; for
2967
 *     example, system-menus.css rather than simply menus.css. Themes can
2968
 *     override module-supplied CSS files based on their filenames, and this
2969
 *     prefixing helps prevent confusing name collisions for theme developers.
2970
 *     See drupal_get_css() where the overrides are performed. Also, if the
2971
 *     direction of the current language is right-to-left (Hebrew, Arabic,
2972
 *     etc.), the function will also look for an RTL CSS file and append it to
2973
 *     the list. The name of this file should have an '-rtl.css' suffix. For
2974
 *     example, a CSS file called 'mymodule-name.css' will have a
2975
 *     'mymodule-name-rtl.css' file added to the list, if exists in the same
2976
 *     directory. This CSS file should contain overrides for properties which
2977
 *     should be reversed or otherwise different in a right-to-left display.
2978
 *   - 'inline': A string of CSS that should be placed in the given scope. Note
2979
 *     that it is better practice to use 'file' stylesheets, rather than
2980
 *     'inline', as the CSS would then be aggregated and cached.
2981
 *   - 'external': The absolute path to an external CSS file that is not hosted
2982
 *     on the local server. These files will not be aggregated if CSS
2983
 *     aggregation is enabled.
2984
 * @param $options
2985
 *   (optional) A string defining the 'type' of CSS that is being added in the
2986
 *   $data parameter ('file', 'inline', or 'external'), or an array which can
2987
 *   have any or all of the following keys:
2988
 *   - 'type': The type of stylesheet being added. Available options are 'file',
2989
 *     'inline' or 'external'. Defaults to 'file'.
2990
 *   - 'basename': Force a basename for the file being added. Modules are
2991
 *     expected to use stylesheets with unique filenames, but integration of
2992
 *     external libraries may make this impossible. The basename of
2993
 *     'modules/node/node.css' is 'node.css'. If the external library "node.js"
2994
 *     ships with a 'node.css', then a different, unique basename would be
2995
 *     'node.js.css'.
2996
 *   - 'group': A number identifying the group in which to add the stylesheet.
2997
 *     Available constants are:
2998
 *     - CSS_SYSTEM: Any system-layer CSS.
2999
 *     - CSS_DEFAULT: (default) Any module-layer CSS.
3000
 *     - CSS_THEME: Any theme-layer CSS.
3001
 *     The group number serves as a weight: the markup for loading a stylesheet
3002
 *     within a lower weight group is output to the page before the markup for
3003
 *     loading a stylesheet within a higher weight group, so CSS within higher
3004
 *     weight groups take precendence over CSS within lower weight groups.
3005
 *   - 'every_page': For optimal front-end performance when aggregation is
3006
 *     enabled, this should be set to TRUE if the stylesheet is present on every
3007
 *     page of the website for users for whom it is present at all. This
3008
 *     defaults to FALSE. It is set to TRUE for stylesheets added via module and
3009
 *     theme .info files. Modules that add stylesheets within hook_init()
3010
 *     implementations, or from other code that ensures that the stylesheet is
3011
 *     added to all website pages, should also set this flag to TRUE. All
3012
 *     stylesheets within the same group that have the 'every_page' flag set to
3013
 *     TRUE and do not have 'preprocess' set to FALSE are aggregated together
3014
 *     into a single aggregate file, and that aggregate file can be reused
3015
 *     across a user's entire site visit, leading to faster navigation between
3016
 *     pages. However, stylesheets that are only needed on pages less frequently
3017
 *     visited, can be added by code that only runs for those particular pages,
3018
 *     and that code should not set the 'every_page' flag. This minimizes the
3019
 *     size of the aggregate file that the user needs to download when first
3020
 *     visiting the website. Stylesheets without the 'every_page' flag are
3021
 *     aggregated into a separate aggregate file. This other aggregate file is
3022
 *     likely to change from page to page, and each new aggregate file needs to
3023
 *     be downloaded when first encountered, so it should be kept relatively
3024
 *     small by ensuring that most commonly needed stylesheets are added to
3025
 *     every page.
3026
 *   - 'weight': The weight of the stylesheet specifies the order in which the
3027
 *     CSS will appear relative to other stylesheets with the same group and
3028
 *     'every_page' flag. The exact ordering of stylesheets is as follows:
3029
 *     - First by group.
3030
 *     - Then by the 'every_page' flag, with TRUE coming before FALSE.
3031
 *     - Then by weight.
3032
 *     - Then by the order in which the CSS was added. For example, all else
3033
 *       being the same, a stylesheet added by a call to drupal_add_css() that
3034
 *       happened later in the page request gets added to the page after one for
3035
 *       which drupal_add_css() happened earlier in the page request.
3036
 *   - 'media': The media type for the stylesheet, e.g., all, print, screen.
3037
 *     Defaults to 'all'.
3038
 *   - 'preprocess': If TRUE and CSS aggregation/compression is enabled, the
3039
 *     styles will be aggregated and compressed. Defaults to TRUE.
3040
 *   - 'browsers': An array containing information specifying which browsers
3041
 *     should load the CSS item. See drupal_pre_render_conditional_comments()
3042
 *     for details.
3043
 *
3044
 * @return
3045
 *   An array of queued cascading stylesheets.
3046
 *
3047
 * @see drupal_get_css()
3048
 */
3049
function drupal_add_css($data = NULL, $options = NULL) {
3050
  $css = &drupal_static(__FUNCTION__, array());
3051
  $count = &drupal_static(__FUNCTION__ . '_count', 0);
3052

    
3053
  // If the $css variable has been reset with drupal_static_reset(), there is
3054
  // no longer any CSS being tracked, so set the counter back to 0 also.
3055
  if (count($css) === 0) {
3056
    $count = 0;
3057
  }
3058

    
3059
  // Construct the options, taking the defaults into consideration.
3060
  if (isset($options)) {
3061
    if (!is_array($options)) {
3062
      $options = array('type' => $options);
3063
    }
3064
  }
3065
  else {
3066
    $options = array();
3067
  }
3068

    
3069
  // Create an array of CSS files for each media type first, since each type needs to be served
3070
  // to the browser differently.
3071
  if (isset($data)) {
3072
    $options += array(
3073
      'type' => 'file',
3074
      'group' => CSS_DEFAULT,
3075
      'weight' => 0,
3076
      'every_page' => FALSE,
3077
      'media' => 'all',
3078
      'preprocess' => TRUE,
3079
      'data' => $data,
3080
      'browsers' => array(),
3081
    );
3082
    $options['browsers'] += array(
3083
      'IE' => TRUE,
3084
      '!IE' => TRUE,
3085
    );
3086

    
3087
    // Files with a query string cannot be preprocessed.
3088
    if ($options['type'] === 'file' && $options['preprocess'] && strpos($options['data'], '?') !== FALSE) {
3089
      $options['preprocess'] = FALSE;
3090
    }
3091

    
3092
    // Always add a tiny value to the weight, to conserve the insertion order.
3093
    $options['weight'] += $count / 1000;
3094
    $count++;
3095

    
3096
    // Add the data to the CSS array depending on the type.
3097
    switch ($options['type']) {
3098
      case 'inline':
3099
        // For inline stylesheets, we don't want to use the $data as the array
3100
        // key as $data could be a very long string of CSS.
3101
        $css[] = $options;
3102
        break;
3103
      default:
3104
        // Local and external files must keep their name as the associative key
3105
        // so the same CSS file is not be added twice.
3106
        $css[$data] = $options;
3107
    }
3108
  }
3109

    
3110
  return $css;
3111
}
3112

    
3113
/**
3114
 * Returns a themed representation of all stylesheets to attach to the page.
3115
 *
3116
 * It loads the CSS in order, with 'module' first, then 'theme' afterwards.
3117
 * This ensures proper cascading of styles so themes can easily override
3118
 * module styles through CSS selectors.
3119
 *
3120
 * Themes may replace module-defined CSS files by adding a stylesheet with the
3121
 * same filename. For example, themes/bartik/system-menus.css would replace
3122
 * modules/system/system-menus.css. This allows themes to override complete
3123
 * CSS files, rather than specific selectors, when necessary.
3124
 *
3125
 * If the original CSS file is being overridden by a theme, the theme is
3126
 * responsible for supplying an accompanying RTL CSS file to replace the
3127
 * module's.
3128
 *
3129
 * @param $css
3130
 *   (optional) An array of CSS files. If no array is provided, the default
3131
 *   stylesheets array is used instead.
3132
 * @param $skip_alter
3133
 *   (optional) If set to TRUE, this function skips calling drupal_alter() on
3134
 *   $css, useful when the calling function passes a $css array that has already
3135
 *   been altered.
3136
 *
3137
 * @return
3138
 *   A string of XHTML CSS tags.
3139
 *
3140
 * @see drupal_add_css()
3141
 */
3142
function drupal_get_css($css = NULL, $skip_alter = FALSE) {
3143
  if (!isset($css)) {
3144
    $css = drupal_add_css();
3145
  }
3146

    
3147
  // Allow modules and themes to alter the CSS items.
3148
  if (!$skip_alter) {
3149
    drupal_alter('css', $css);
3150
  }
3151

    
3152
  // Sort CSS items, so that they appear in the correct order.
3153
  uasort($css, 'drupal_sort_css_js');
3154

    
3155
  // Provide the page with information about the individual CSS files used,
3156
  // information not otherwise available when CSS aggregation is enabled. The
3157
  // setting is attached later in this function, but is set here, so that CSS
3158
  // files removed below are still considered "used" and prevented from being
3159
  // added in a later AJAX request.
3160
  // Skip if no files were added to the page or jQuery.extend() will overwrite
3161
  // the Drupal.settings.ajaxPageState.css object with an empty array.
3162
  if (!empty($css)) {
3163
    // Cast the array to an object to be on the safe side even if not empty.
3164
    $setting['ajaxPageState']['css'] = (object) array_fill_keys(array_keys($css), 1);
3165
  }
3166

    
3167
  // Remove the overridden CSS files. Later CSS files override former ones.
3168
  $previous_item = array();
3169
  foreach ($css as $key => $item) {
3170
    if ($item['type'] == 'file') {
3171
      // If defined, force a unique basename for this file.
3172
      $basename = isset($item['basename']) ? $item['basename'] : drupal_basename($item['data']);
3173
      if (isset($previous_item[$basename])) {
3174
        // Remove the previous item that shared the same base name.
3175
        unset($css[$previous_item[$basename]]);
3176
      }
3177
      $previous_item[$basename] = $key;
3178
    }
3179
  }
3180

    
3181
  // Render the HTML needed to load the CSS.
3182
  $styles = array(
3183
    '#type' => 'styles',
3184
    '#items' => $css,
3185
  );
3186

    
3187
  if (!empty($setting)) {
3188
    $styles['#attached']['js'][] = array('type' => 'setting', 'data' => $setting);
3189
  }
3190

    
3191
  return drupal_render($styles);
3192
}
3193

    
3194
/**
3195
 * Sorts CSS and JavaScript resources.
3196
 *
3197
 * Callback for uasort() within:
3198
 * - drupal_get_css()
3199
 * - drupal_get_js()
3200
 *
3201
 * This sort order helps optimize front-end performance while providing modules
3202
 * and themes with the necessary control for ordering the CSS and JavaScript
3203
 * appearing on a page.
3204
 *
3205
 * @param $a
3206
 *   First item for comparison. The compared items should be associative arrays
3207
 *   of member items from drupal_add_css() or drupal_add_js().
3208
 * @param $b
3209
 *   Second item for comparison.
3210
 *
3211
 * @see drupal_add_css()
3212
 * @see drupal_add_js()
3213
 */
3214
function drupal_sort_css_js($a, $b) {
3215
  // First order by group, so that, for example, all items in the CSS_SYSTEM
3216
  // group appear before items in the CSS_DEFAULT group, which appear before
3217
  // all items in the CSS_THEME group. Modules may create additional groups by
3218
  // defining their own constants.
3219
  if ($a['group'] < $b['group']) {
3220
    return -1;
3221
  }
3222
  elseif ($a['group'] > $b['group']) {
3223
    return 1;
3224
  }
3225
  // Within a group, order all infrequently needed, page-specific files after
3226
  // common files needed throughout the website. Separating this way allows for
3227
  // the aggregate file generated for all of the common files to be reused
3228
  // across a site visit without being cut by a page using a less common file.
3229
  elseif ($a['every_page'] && !$b['every_page']) {
3230
    return -1;
3231
  }
3232
  elseif (!$a['every_page'] && $b['every_page']) {
3233
    return 1;
3234
  }
3235
  // Finally, order by weight.
3236
  elseif ($a['weight'] < $b['weight']) {
3237
    return -1;
3238
  }
3239
  elseif ($a['weight'] > $b['weight']) {
3240
    return 1;
3241
  }
3242
  else {
3243
    return 0;
3244
  }
3245
}
3246

    
3247
/**
3248
 * Default callback to group CSS items.
3249
 *
3250
 * This function arranges the CSS items that are in the #items property of the
3251
 * styles element into groups. Arranging the CSS items into groups serves two
3252
 * purposes. When aggregation is enabled, files within a group are aggregated
3253
 * into a single file, significantly improving page loading performance by
3254
 * minimizing network traffic overhead. When aggregation is disabled, grouping
3255
 * allows multiple files to be loaded from a single STYLE tag, enabling sites
3256
 * with many modules enabled or a complex theme being used to stay within IE's
3257
 * 31 CSS inclusion tag limit: http://drupal.org/node/228818.
3258
 *
3259
 * This function puts multiple items into the same group if they are groupable
3260
 * and if they are for the same 'media' and 'browsers'. Items of the 'file' type
3261
 * are groupable if their 'preprocess' flag is TRUE, items of the 'inline' type
3262
 * are always groupable, and items of the 'external' type are never groupable.
3263
 * This function also ensures that the process of grouping items does not change
3264
 * their relative order. This requirement may result in multiple groups for the
3265
 * same type, media, and browsers, if needed to accommodate other items in
3266
 * between.
3267
 *
3268
 * @param $css
3269
 *   An array of CSS items, as returned by drupal_add_css(), but after
3270
 *   alteration performed by drupal_get_css().
3271
 *
3272
 * @return
3273
 *   An array of CSS groups. Each group contains the same keys (e.g., 'media',
3274
 *   'data', etc.) as a CSS item from the $css parameter, with the value of
3275
 *   each key applying to the group as a whole. Each group also contains an
3276
 *   'items' key, which is the subset of items from $css that are in the group.
3277
 *
3278
 * @see drupal_pre_render_styles()
3279
 * @see system_element_info()
3280
 */
3281
function drupal_group_css($css) {
3282
  $groups = array();
3283
  // If a group can contain multiple items, we track the information that must
3284
  // be the same for each item in the group, so that when we iterate the next
3285
  // item, we can determine if it can be put into the current group, or if a
3286
  // new group needs to be made for it.
3287
  $current_group_keys = NULL;
3288
  // When creating a new group, we pre-increment $i, so by initializing it to
3289
  // -1, the first group will have index 0.
3290
  $i = -1;
3291
  foreach ($css as $item) {
3292
    // The browsers for which the CSS item needs to be loaded is part of the
3293
    // information that determines when a new group is needed, but the order of
3294
    // keys in the array doesn't matter, and we don't want a new group if all
3295
    // that's different is that order.
3296
    ksort($item['browsers']);
3297

    
3298
    // If the item can be grouped with other items, set $group_keys to an array
3299
    // of information that must be the same for all items in its group. If the
3300
    // item can't be grouped with other items, set $group_keys to FALSE. We
3301
    // put items into a group that can be aggregated together: whether they will
3302
    // be aggregated is up to the _drupal_css_aggregate() function or an
3303
    // override of that function specified in hook_css_alter(), but regardless
3304
    // of the details of that function, a group represents items that can be
3305
    // aggregated. Since a group may be rendered with a single HTML tag, all
3306
    // items in the group must share the same information that would need to be
3307
    // part of that HTML tag.
3308
    switch ($item['type']) {
3309
      case 'file':
3310
        // Group file items if their 'preprocess' flag is TRUE.
3311
        // Help ensure maximum reuse of aggregate files by only grouping
3312
        // together items that share the same 'group' value and 'every_page'
3313
        // flag. See drupal_add_css() for details about that.
3314
        $group_keys = $item['preprocess'] ? array($item['type'], $item['group'], $item['every_page'], $item['media'], $item['browsers']) : FALSE;
3315
        break;
3316
      case 'inline':
3317
        // Always group inline items.
3318
        $group_keys = array($item['type'], $item['media'], $item['browsers']);
3319
        break;
3320
      case 'external':
3321
        // Do not group external items.
3322
        $group_keys = FALSE;
3323
        break;
3324
    }
3325

    
3326
    // If the group keys don't match the most recent group we're working with,
3327
    // then a new group must be made.
3328
    if ($group_keys !== $current_group_keys) {
3329
      $i++;
3330
      // Initialize the new group with the same properties as the first item
3331
      // being placed into it. The item's 'data' and 'weight' properties are
3332
      // unique to the item and should not be carried over to the group.
3333
      $groups[$i] = $item;
3334
      unset($groups[$i]['data'], $groups[$i]['weight']);
3335
      $groups[$i]['items'] = array();
3336
      $current_group_keys = $group_keys ? $group_keys : NULL;
3337
    }
3338

    
3339
    // Add the item to the current group.
3340
    $groups[$i]['items'][] = $item;
3341
  }
3342
  return $groups;
3343
}
3344

    
3345
/**
3346
 * Default callback to aggregate CSS files and inline content.
3347
 *
3348
 * Having the browser load fewer CSS files results in much faster page loads
3349
 * than when it loads many small files. This function aggregates files within
3350
 * the same group into a single file unless the site-wide setting to do so is
3351
 * disabled (commonly the case during site development). To optimize download,
3352
 * it also compresses the aggregate files by removing comments, whitespace, and
3353
 * other unnecessary content. Additionally, this functions aggregates inline
3354
 * content together, regardless of the site-wide aggregation setting.
3355
 *
3356
 * @param $css_groups
3357
 *   An array of CSS groups as returned by drupal_group_css(). This function
3358
 *   modifies the group's 'data' property for each group that is aggregated.
3359
 *
3360
 * @see drupal_group_css()
3361
 * @see drupal_pre_render_styles()
3362
 * @see system_element_info()
3363
 */
3364
function drupal_aggregate_css(&$css_groups) {
3365
  $preprocess_css = (variable_get('preprocess_css', FALSE) && (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update'));
3366

    
3367
  // For each group that needs aggregation, aggregate its items.
3368
  foreach ($css_groups as $key => $group) {
3369
    switch ($group['type']) {
3370
      // If a file group can be aggregated into a single file, do so, and set
3371
      // the group's data property to the file path of the aggregate file.
3372
      case 'file':
3373
        if ($group['preprocess'] && $preprocess_css) {
3374
          $css_groups[$key]['data'] = drupal_build_css_cache($group['items']);
3375
        }
3376
        break;
3377
      // Aggregate all inline CSS content into the group's data property.
3378
      case 'inline':
3379
        $css_groups[$key]['data'] = '';
3380
        foreach ($group['items'] as $item) {
3381
          $css_groups[$key]['data'] .= drupal_load_stylesheet_content($item['data'], $item['preprocess']);
3382
        }
3383
        break;
3384
    }
3385
  }
3386
}
3387

    
3388
/**
3389
 * #pre_render callback to add the elements needed for CSS tags to be rendered.
3390
 *
3391
 * For production websites, LINK tags are preferable to STYLE tags with @import
3392
 * statements, because:
3393
 * - They are the standard tag intended for linking to a resource.
3394
 * - On Firefox 2 and perhaps other browsers, CSS files included with @import
3395
 *   statements don't get saved when saving the complete web page for offline
3396
 *   use: http://drupal.org/node/145218.
3397
 * - On IE, if only LINK tags and no @import statements are used, all the CSS
3398
 *   files are downloaded in parallel, resulting in faster page load, but if
3399
 *   @import statements are used and span across multiple STYLE tags, all the
3400
 *   ones from one STYLE tag must be downloaded before downloading begins for
3401
 *   the next STYLE tag. Furthermore, IE7 does not support media declaration on
3402
 *   the @import statement, so multiple STYLE tags must be used when different
3403
 *   files are for different media types. Non-IE browsers always download in
3404
 *   parallel, so this is an IE-specific performance quirk:
3405
 *   http://www.stevesouders.com/blog/2009/04/09/dont-use-import/.
3406
 *
3407
 * However, IE has an annoying limit of 31 total CSS inclusion tags
3408
 * (http://drupal.org/node/228818) and LINK tags are limited to one file per
3409
 * tag, whereas STYLE tags can contain multiple @import statements allowing
3410
 * multiple files to be loaded per tag. When CSS aggregation is disabled, a
3411
 * Drupal site can easily have more than 31 CSS files that need to be loaded, so
3412
 * using LINK tags exclusively would result in a site that would display
3413
 * incorrectly in IE. Depending on different needs, different strategies can be
3414
 * employed to decide when to use LINK tags and when to use STYLE tags.
3415
 *
3416
 * The strategy employed by this function is to use LINK tags for all aggregate
3417
 * files and for all files that cannot be aggregated (e.g., if 'preprocess' is
3418
 * set to FALSE or the type is 'external'), and to use STYLE tags for groups
3419
 * of files that could be aggregated together but aren't (e.g., if the site-wide
3420
 * aggregation setting is disabled). This results in all LINK tags when
3421
 * aggregation is enabled, a guarantee that as many or only slightly more tags
3422
 * are used with aggregation disabled than enabled (so that if the limit were to
3423
 * be crossed with aggregation enabled, the site developer would also notice the
3424
 * problem while aggregation is disabled), and an easy way for a developer to
3425
 * view HTML source while aggregation is disabled and know what files will be
3426
 * aggregated together when aggregation becomes enabled.
3427
 *
3428
 * This function evaluates the aggregation enabled/disabled condition on a group
3429
 * by group basis by testing whether an aggregate file has been made for the
3430
 * group rather than by testing the site-wide aggregation setting. This allows
3431
 * this function to work correctly even if modules have implemented custom
3432
 * logic for grouping and aggregating files.
3433
 *
3434
 * @param $element
3435
 *   A render array containing:
3436
 *   - '#items': The CSS items as returned by drupal_add_css() and altered by
3437
 *     drupal_get_css().
3438
 *   - '#group_callback': A function to call to group #items to enable the use
3439
 *     of fewer tags by aggregating files and/or using multiple @import
3440
 *     statements within a single tag.
3441
 *   - '#aggregate_callback': A function to call to aggregate the items within
3442
 *     the groups arranged by the #group_callback function.
3443
 *
3444
 * @return
3445
 *   A render array that will render to a string of XHTML CSS tags.
3446
 *
3447
 * @see drupal_get_css()
3448
 */
3449
function drupal_pre_render_styles($elements) {
3450
  // Group and aggregate the items.
3451
  if (isset($elements['#group_callback'])) {
3452
    $elements['#groups'] = $elements['#group_callback']($elements['#items']);
3453
  }
3454
  if (isset($elements['#aggregate_callback'])) {
3455
    $elements['#aggregate_callback']($elements['#groups']);
3456
  }
3457

    
3458
  // A dummy query-string is added to filenames, to gain control over
3459
  // browser-caching. The string changes on every update or full cache
3460
  // flush, forcing browsers to load a new copy of the files, as the
3461
  // URL changed.
3462
  $query_string = variable_get('css_js_query_string', '0');
3463

    
3464
  // For inline CSS to validate as XHTML, all CSS containing XHTML needs to be
3465
  // wrapped in CDATA. To make that backwards compatible with HTML 4, we need to
3466
  // comment out the CDATA-tag.
3467
  $embed_prefix = "\n<!--/*--><![CDATA[/*><!--*/\n";
3468
  $embed_suffix = "\n/*]]>*/-->\n";
3469

    
3470
  // Defaults for LINK and STYLE elements.
3471
  $link_element_defaults = array(
3472
    '#type' => 'html_tag',
3473
    '#tag' => 'link',
3474
    '#attributes' => array(
3475
      'type' => 'text/css',
3476
      'rel' => 'stylesheet',
3477
    ),
3478
  );
3479
  $style_element_defaults = array(
3480
    '#type' => 'html_tag',
3481
    '#tag' => 'style',
3482
    '#attributes' => array(
3483
      'type' => 'text/css',
3484
    ),
3485
  );
3486

    
3487
  // Loop through each group.
3488
  foreach ($elements['#groups'] as $group) {
3489
    switch ($group['type']) {
3490
      // For file items, there are three possibilites.
3491
      // - The group has been aggregated: in this case, output a LINK tag for
3492
      //   the aggregate file.
3493
      // - The group can be aggregated but has not been (most likely because
3494
      //   the site administrator disabled the site-wide setting): in this case,
3495
      //   output as few STYLE tags for the group as possible, using @import
3496
      //   statement for each file in the group. This enables us to stay within
3497
      //   IE's limit of 31 total CSS inclusion tags.
3498
      // - The group contains items not eligible for aggregation (their
3499
      //   'preprocess' flag has been set to FALSE): in this case, output a LINK
3500
      //   tag for each file.
3501
      case 'file':
3502
        // The group has been aggregated into a single file: output a LINK tag
3503
        // for the aggregate file.
3504
        if (isset($group['data'])) {
3505
          $element = $link_element_defaults;
3506
          $element['#attributes']['href'] = file_create_url($group['data']);
3507
          $element['#attributes']['media'] = $group['media'];
3508
          $element['#browsers'] = $group['browsers'];
3509
          $elements[] = $element;
3510
        }
3511
        // The group can be aggregated, but hasn't been: combine multiple items
3512
        // into as few STYLE tags as possible.
3513
        elseif ($group['preprocess']) {
3514
          $import = array();
3515
          foreach ($group['items'] as $item) {
3516
            // A theme's .info file may have an entry for a file that doesn't
3517
            // exist as a way of overriding a module or base theme CSS file from
3518
            // being added to the page. Normally, file_exists() calls that need
3519
            // to run for every page request should be minimized, but this one
3520
            // is okay, because it only runs when CSS aggregation is disabled.
3521
            // On a server under heavy enough load that file_exists() calls need
3522
            // to be minimized, CSS aggregation should be enabled, in which case
3523
            // this code is not run. When aggregation is enabled,
3524
            // drupal_load_stylesheet() checks file_exists(), but only when
3525
            // building the aggregate file, which is then reused for many page
3526
            // requests.
3527
            if (file_exists($item['data'])) {
3528
              // The dummy query string needs to be added to the URL to control
3529
              // browser-caching. IE7 does not support a media type on the
3530
              // @import statement, so we instead specify the media for the
3531
              // group on the STYLE tag.
3532
              $import[] = '@import url("' . check_plain(file_create_url($item['data']) . '?' . $query_string) . '");';
3533
            }
3534
          }
3535
          // In addition to IE's limit of 31 total CSS inclusion tags, it also
3536
          // has a limit of 31 @import statements per STYLE tag.
3537
          while (!empty($import)) {
3538
            $import_batch = array_slice($import, 0, 31);
3539
            $import = array_slice($import, 31);
3540
            $element = $style_element_defaults;
3541
            // This simplifies the JavaScript regex, allowing each line
3542
            // (separated by \n) to be treated as a completely different string.
3543
            // This means that we can use ^ and $ on one line at a time, and not
3544
            // worry about style tags since they'll never match the regex.
3545
            $element['#value'] = "\n" . implode("\n", $import_batch) . "\n";
3546
            $element['#attributes']['media'] = $group['media'];
3547
            $element['#browsers'] = $group['browsers'];
3548
            $elements[] = $element;
3549
          }
3550
        }
3551
        // The group contains items ineligible for aggregation: output a LINK
3552
        // tag for each file.
3553
        else {
3554
          foreach ($group['items'] as $item) {
3555
            $element = $link_element_defaults;
3556
            // We do not check file_exists() here, because this code runs for
3557
            // files whose 'preprocess' is set to FALSE, and therefore, even
3558
            // when aggregation is enabled, and we want to avoid needlessly
3559
            // taxing a server that may be under heavy load. The file_exists()
3560
            // performed above for files whose 'preprocess' is TRUE is done for
3561
            // the benefit of theme .info files, but code that deals with files
3562
            // whose 'preprocess' is FALSE is responsible for ensuring the file
3563
            // exists.
3564
            // The dummy query string needs to be added to the URL to control
3565
            // browser-caching.
3566
            $query_string_separator = (strpos($item['data'], '?') !== FALSE) ? '&' : '?';
3567
            $element['#attributes']['href'] = file_create_url($item['data']) . $query_string_separator . $query_string;
3568
            $element['#attributes']['media'] = $item['media'];
3569
            $element['#browsers'] = $group['browsers'];
3570
            $elements[] = $element;
3571
          }
3572
        }
3573
        break;
3574
      // For inline content, the 'data' property contains the CSS content. If
3575
      // the group's 'data' property is set, then output it in a single STYLE
3576
      // tag. Otherwise, output a separate STYLE tag for each item.
3577
      case 'inline':
3578
        if (isset($group['data'])) {
3579
          $element = $style_element_defaults;
3580
          $element['#value'] = $group['data'];
3581
          $element['#value_prefix'] = $embed_prefix;
3582
          $element['#value_suffix'] = $embed_suffix;
3583
          $element['#attributes']['media'] = $group['media'];
3584
          $element['#browsers'] = $group['browsers'];
3585
          $elements[] = $element;
3586
        }
3587
        else {
3588
          foreach ($group['items'] as $item) {
3589
            $element = $style_element_defaults;
3590
            $element['#value'] = $item['data'];
3591
            $element['#value_prefix'] = $embed_prefix;
3592
            $element['#value_suffix'] = $embed_suffix;
3593
            $element['#attributes']['media'] = $item['media'];
3594
            $element['#browsers'] = $group['browsers'];
3595
            $elements[] = $element;
3596
          }
3597
        }
3598
        break;
3599
      // Output a LINK tag for each external item. The item's 'data' property
3600
      // contains the full URL.
3601
      case 'external':
3602
        foreach ($group['items'] as $item) {
3603
          $element = $link_element_defaults;
3604
          $element['#attributes']['href'] = $item['data'];
3605
          $element['#attributes']['media'] = $item['media'];
3606
          $element['#browsers'] = $group['browsers'];
3607
          $elements[] = $element;
3608
        }
3609
        break;
3610
    }
3611
  }
3612

    
3613
  return $elements;
3614
}
3615

    
3616
/**
3617
 * Aggregates and optimizes CSS files into a cache file in the files directory.
3618
 *
3619
 * The file name for the CSS cache file is generated from the hash of the
3620
 * aggregated contents of the files in $css. This forces proxies and browsers
3621
 * to download new CSS when the CSS changes.
3622
 *
3623
 * The cache file name is retrieved on a page load via a lookup variable that
3624
 * contains an associative array. The array key is the hash of the file names
3625
 * in $css while the value is the cache file name. The cache file is generated
3626
 * in two cases. First, if there is no file name value for the key, which will
3627
 * happen if a new file name has been added to $css or after the lookup
3628
 * variable is emptied to force a rebuild of the cache. Second, the cache file
3629
 * is generated if it is missing on disk. Old cache files are not deleted
3630
 * immediately when the lookup variable is emptied, but are deleted after a set
3631
 * period by drupal_delete_file_if_stale(). This ensures that files referenced
3632
 * by a cached page will still be available.
3633
 *
3634
 * @param $css
3635
 *   An array of CSS files to aggregate and compress into one file.
3636
 *
3637
 * @return
3638
 *   The URI of the CSS cache file, or FALSE if the file could not be saved.
3639
 */
3640
function drupal_build_css_cache($css) {
3641
  $data = '';
3642
  $uri = '';
3643
  $map = variable_get('drupal_css_cache_files', array());
3644
  // Create a new array so that only the file names are used to create the hash.
3645
  // This prevents new aggregates from being created unnecessarily.
3646
  $css_data = array();
3647
  foreach ($css as $css_file) {
3648
    $css_data[] = $css_file['data'];
3649
  }
3650
  $key = hash('sha256', serialize($css_data));
3651
  if (isset($map[$key])) {
3652
    $uri = $map[$key];
3653
  }
3654

    
3655
  if (empty($uri) || !file_exists($uri)) {
3656
    // Build aggregate CSS file.
3657
    foreach ($css as $stylesheet) {
3658
      // Only 'file' stylesheets can be aggregated.
3659
      if ($stylesheet['type'] == 'file') {
3660
        $contents = drupal_load_stylesheet($stylesheet['data'], TRUE);
3661

    
3662
        // Build the base URL of this CSS file: start with the full URL.
3663
        $css_base_url = file_create_url($stylesheet['data']);
3664
        // Move to the parent.
3665
        $css_base_url = substr($css_base_url, 0, strrpos($css_base_url, '/'));
3666
        // Simplify to a relative URL if the stylesheet URL starts with the
3667
        // base URL of the website.
3668
        if (substr($css_base_url, 0, strlen($GLOBALS['base_root'])) == $GLOBALS['base_root']) {
3669
          $css_base_url = substr($css_base_url, strlen($GLOBALS['base_root']));
3670
        }
3671

    
3672
        _drupal_build_css_path(NULL, $css_base_url . '/');
3673
        // Anchor all paths in the CSS with its base URL, ignoring external and absolute paths.
3674
        $data .= preg_replace_callback('/url\(\s*[\'"]?(?![a-z]+:|\/+)([^\'")]+)[\'"]?\s*\)/i', '_drupal_build_css_path', $contents);
3675
      }
3676
    }
3677

    
3678
    // Per the W3C specification at http://www.w3.org/TR/REC-CSS2/cascade.html#at-import,
3679
    // @import rules must proceed any other style, so we move those to the top.
3680
    $regexp = '/@import[^;]+;/i';
3681
    preg_match_all($regexp, $data, $matches);
3682
    $data = preg_replace($regexp, '', $data);
3683
    $data = implode('', $matches[0]) . $data;
3684

    
3685
    // Prefix filename to prevent blocking by firewalls which reject files
3686
    // starting with "ad*".
3687
    $filename = 'css_' . drupal_hash_base64($data) . '.css';
3688
    // Create the css/ within the files folder.
3689
    $csspath = 'public://css';
3690
    $uri = $csspath . '/' . $filename;
3691
    // Create the CSS file.
3692
    file_prepare_directory($csspath, FILE_CREATE_DIRECTORY);
3693
    if (!file_exists($uri) && !file_unmanaged_save_data($data, $uri, FILE_EXISTS_REPLACE)) {
3694
      return FALSE;
3695
    }
3696
    // If CSS gzip compression is enabled, clean URLs are enabled (which means
3697
    // that rewrite rules are working) and the zlib extension is available then
3698
    // create a gzipped version of this file. This file is served conditionally
3699
    // to browsers that accept gzip using .htaccess rules.
3700
    if (variable_get('css_gzip_compression', TRUE) && variable_get('clean_url', 0) && extension_loaded('zlib')) {
3701
      if (!file_exists($uri . '.gz') && !file_unmanaged_save_data(gzencode($data, 9, FORCE_GZIP), $uri . '.gz', FILE_EXISTS_REPLACE)) {
3702
        return FALSE;
3703
      }
3704
    }
3705
    // Save the updated map.
3706
    $map[$key] = $uri;
3707
    variable_set('drupal_css_cache_files', $map);
3708
  }
3709
  return $uri;
3710
}
3711

    
3712
/**
3713
 * Prefixes all paths within a CSS file for drupal_build_css_cache().
3714
 */
3715
function _drupal_build_css_path($matches, $base = NULL) {
3716
  $_base = &drupal_static(__FUNCTION__);
3717
  // Store base path for preg_replace_callback.
3718
  if (isset($base)) {
3719
    $_base = $base;
3720
  }
3721

    
3722
  // Prefix with base and remove '../' segments where possible.
3723
  $path = $_base . $matches[1];
3724
  $last = '';
3725
  while ($path != $last) {
3726
    $last = $path;
3727
    $path = preg_replace('`(^|/)(?!\.\./)([^/]+)/\.\./`', '$1', $path);
3728
  }
3729
  return 'url(' . $path . ')';
3730
}
3731

    
3732
/**
3733
 * Loads the stylesheet and resolves all @import commands.
3734
 *
3735
 * Loads a stylesheet and replaces @import commands with the contents of the
3736
 * imported file. Use this instead of file_get_contents when processing
3737
 * stylesheets.
3738
 *
3739
 * The returned contents are compressed removing white space and comments only
3740
 * when CSS aggregation is enabled. This optimization will not apply for
3741
 * color.module enabled themes with CSS aggregation turned off.
3742
 *
3743
 * @param $file
3744
 *   Name of the stylesheet to be processed.
3745
 * @param $optimize
3746
 *   Defines if CSS contents should be compressed or not.
3747
 * @param $reset_basepath
3748
 *   Used internally to facilitate recursive resolution of @import commands.
3749
 *
3750
 * @return
3751
 *   Contents of the stylesheet, including any resolved @import commands.
3752
 */
3753
function drupal_load_stylesheet($file, $optimize = NULL, $reset_basepath = TRUE) {
3754
  // These statics are not cache variables, so we don't use drupal_static().
3755
  static $_optimize, $basepath;
3756
  if ($reset_basepath) {
3757
    $basepath = '';
3758
  }
3759
  // Store the value of $optimize for preg_replace_callback with nested
3760
  // @import loops.
3761
  if (isset($optimize)) {
3762
    $_optimize = $optimize;
3763
  }
3764

    
3765
  // Stylesheets are relative one to each other. Start by adding a base path
3766
  // prefix provided by the parent stylesheet (if necessary).
3767
  if ($basepath && !file_uri_scheme($file)) {
3768
    $file = $basepath . '/' . $file;
3769
  }
3770
  // Store the parent base path to restore it later.
3771
  $parent_base_path = $basepath;
3772
  // Set the current base path to process possible child imports.
3773
  $basepath = dirname($file);
3774

    
3775
  // Load the CSS stylesheet. We suppress errors because themes may specify
3776
  // stylesheets in their .info file that don't exist in the theme's path,
3777
  // but are merely there to disable certain module CSS files.
3778
  $content = '';
3779
  if ($contents = @file_get_contents($file)) {
3780
    // Return the processed stylesheet.
3781
    $content = drupal_load_stylesheet_content($contents, $_optimize);
3782
  }
3783

    
3784
  // Restore the parent base path as the file and its childen are processed.
3785
  $basepath = $parent_base_path;
3786
  return $content;
3787
}
3788

    
3789
/**
3790
 * Processes the contents of a stylesheet for aggregation.
3791
 *
3792
 * @param $contents
3793
 *   The contents of the stylesheet.
3794
 * @param $optimize
3795
 *   (optional) Boolean whether CSS contents should be minified. Defaults to
3796
 *   FALSE.
3797
 *
3798
 * @return
3799
 *   Contents of the stylesheet including the imported stylesheets.
3800
 */
3801
function drupal_load_stylesheet_content($contents, $optimize = FALSE) {
3802
  // Remove multiple charset declarations for standards compliance (and fixing Safari problems).
3803
  $contents = preg_replace('/^@charset\s+[\'"](\S*?)\b[\'"];/i', '', $contents);
3804

    
3805
  if ($optimize) {
3806
    // Perform some safe CSS optimizations.
3807
    // Regexp to match comment blocks.
3808
    $comment     = '/\*[^*]*\*+(?:[^/*][^*]*\*+)*/';
3809
    // Regexp to match double quoted strings.
3810
    $double_quot = '"[^"\\\\]*(?:\\\\.[^"\\\\]*)*"';
3811
    // Regexp to match single quoted strings.
3812
    $single_quot = "'[^'\\\\]*(?:\\\\.[^'\\\\]*)*'";
3813
    // Strip all comment blocks, but keep double/single quoted strings.
3814
    $contents = preg_replace(
3815
      "<($double_quot|$single_quot)|$comment>Ss",
3816
      "$1",
3817
      $contents
3818
    );
3819
    // Remove certain whitespace.
3820
    // There are different conditions for removing leading and trailing
3821
    // whitespace.
3822
    // @see http://php.net/manual/regexp.reference.subpatterns.php
3823
    $contents = preg_replace('<
3824
      # Strip leading and trailing whitespace.
3825
        \s*([@{};,])\s*
3826
      # Strip only leading whitespace from:
3827
      # - Closing parenthesis: Retain "@media (bar) and foo".
3828
      | \s+([\)])
3829
      # Strip only trailing whitespace from:
3830
      # - Opening parenthesis: Retain "@media (bar) and foo".
3831
      # - Colon: Retain :pseudo-selectors.
3832
      | ([\(:])\s+
3833
    >xS',
3834
      // Only one of the three capturing groups will match, so its reference
3835
      // will contain the wanted value and the references for the
3836
      // two non-matching groups will be replaced with empty strings.
3837
      '$1$2$3',
3838
      $contents
3839
    );
3840
    // End the file with a new line.
3841
    $contents = trim($contents);
3842
    $contents .= "\n";
3843
  }
3844

    
3845
  // Replaces @import commands with the actual stylesheet content.
3846
  // This happens recursively but omits external files.
3847
  $contents = preg_replace_callback('/@import\s*(?:url\(\s*)?[\'"]?(?![a-z]+:)(?!\/\/)([^\'"\()]+)[\'"]?\s*\)?\s*;/', '_drupal_load_stylesheet', $contents);
3848
  return $contents;
3849
}
3850

    
3851
/**
3852
 * Loads stylesheets recursively and returns contents with corrected paths.
3853
 *
3854
 * This function is used for recursive loading of stylesheets and
3855
 * returns the stylesheet content with all url() paths corrected.
3856
 */
3857
function _drupal_load_stylesheet($matches) {
3858
  $filename = $matches[1];
3859
  // Load the imported stylesheet and replace @import commands in there as well.
3860
  $file = drupal_load_stylesheet($filename, NULL, FALSE);
3861

    
3862
  // Determine the file's directory.
3863
  $directory = dirname($filename);
3864
  // If the file is in the current directory, make sure '.' doesn't appear in
3865
  // the url() path.
3866
  $directory = $directory == '.' ? '' : $directory .'/';
3867

    
3868
  // Alter all internal url() paths. Leave external paths alone. We don't need
3869
  // to normalize absolute paths here (i.e. remove folder/... segments) because
3870
  // that will be done later.
3871
  return preg_replace('/url\(\s*([\'"]?)(?![a-z]+:|\/+)([^\'")]+)([\'"]?)\s*\)/i', 'url(\1' . $directory . '\2\3)', $file);
3872
}
3873

    
3874
/**
3875
 * Deletes old cached CSS files.
3876
 */
3877
function drupal_clear_css_cache() {
3878
  variable_del('drupal_css_cache_files');
3879
  file_scan_directory('public://css', '/.*/', array('callback' => 'drupal_delete_file_if_stale'));
3880
}
3881

    
3882
/**
3883
 * Callback to delete files modified more than a set time ago.
3884
 */
3885
function drupal_delete_file_if_stale($uri) {
3886
  // Default stale file threshold is 30 days.
3887
  if (REQUEST_TIME - filemtime($uri) > variable_get('drupal_stale_file_threshold', 2592000)) {
3888
    file_unmanaged_delete($uri);
3889
  }
3890
}
3891

    
3892
/**
3893
 * Prepares a string for use as a CSS identifier (element, class, or ID name).
3894
 *
3895
 * http://www.w3.org/TR/CSS21/syndata.html#characters shows the syntax for valid
3896
 * CSS identifiers (including element names, classes, and IDs in selectors.)
3897
 *
3898
 * @param $identifier
3899
 *   The identifier to clean.
3900
 * @param $filter
3901
 *   An array of string replacements to use on the identifier.
3902
 *
3903
 * @return
3904
 *   The cleaned identifier.
3905
 */
3906
function drupal_clean_css_identifier($identifier, $filter = array(' ' => '-', '_' => '-', '/' => '-', '[' => '-', ']' => '')) {
3907
  // Use the advanced drupal_static() pattern, since this is called very often.
3908
  static $drupal_static_fast;
3909
  if (!isset($drupal_static_fast)) {
3910
    $drupal_static_fast['allow_css_double_underscores'] = &drupal_static(__FUNCTION__ . ':allow_css_double_underscores');
3911
  }
3912
  $allow_css_double_underscores = &$drupal_static_fast['allow_css_double_underscores'];
3913
  if (!isset($allow_css_double_underscores)) {
3914
    $allow_css_double_underscores = variable_get('allow_css_double_underscores', FALSE);
3915
  }
3916

    
3917
  // Preserve BEM-style double-underscores depending on custom setting.
3918
  if ($allow_css_double_underscores) {
3919
    $filter['__'] = '__';
3920
  }
3921

    
3922
  // By default, we filter using Drupal's coding standards.
3923
  $identifier = strtr($identifier, $filter);
3924

    
3925
  // Valid characters in a CSS identifier are:
3926
  // - the hyphen (U+002D)
3927
  // - a-z (U+0030 - U+0039)
3928
  // - A-Z (U+0041 - U+005A)
3929
  // - the underscore (U+005F)
3930
  // - 0-9 (U+0061 - U+007A)
3931
  // - ISO 10646 characters U+00A1 and higher
3932
  // We strip out any character not in the above list.
3933
  $identifier = preg_replace('/[^\x{002D}\x{0030}-\x{0039}\x{0041}-\x{005A}\x{005F}\x{0061}-\x{007A}\x{00A1}-\x{FFFF}]/u', '', $identifier);
3934

    
3935
  return $identifier;
3936
}
3937

    
3938
/**
3939
 * Prepares a string for use as a valid class name.
3940
 *
3941
 * Do not pass one string containing multiple classes as they will be
3942
 * incorrectly concatenated with dashes, i.e. "one two" will become "one-two".
3943
 *
3944
 * @param $class
3945
 *   The class name to clean.
3946
 *
3947
 * @return
3948
 *   The cleaned class name.
3949
 */
3950
function drupal_html_class($class) {
3951
  // The output of this function will never change, so this uses a normal
3952
  // static instead of drupal_static().
3953
  static $classes = array();
3954

    
3955
  if (!isset($classes[$class])) {
3956
    $classes[$class] = drupal_clean_css_identifier(drupal_strtolower($class));
3957
  }
3958
  return $classes[$class];
3959
}
3960

    
3961
/**
3962
 * Prepares a string for use as a valid HTML ID and guarantees uniqueness.
3963
 *
3964
 * This function ensures that each passed HTML ID value only exists once on the
3965
 * page. By tracking the already returned ids, this function enables forms,
3966
 * blocks, and other content to be output multiple times on the same page,
3967
 * without breaking (X)HTML validation.
3968
 *
3969
 * For already existing IDs, a counter is appended to the ID string. Therefore,
3970
 * JavaScript and CSS code should not rely on any value that was generated by
3971
 * this function and instead should rely on manually added CSS classes or
3972
 * similarly reliable constructs.
3973
 *
3974
 * Two consecutive hyphens separate the counter from the original ID. To manage
3975
 * uniqueness across multiple Ajax requests on the same page, Ajax requests
3976
 * POST an array of all IDs currently present on the page, which are used to
3977
 * prime this function's cache upon first invocation.
3978
 *
3979
 * To allow reverse-parsing of IDs submitted via Ajax, any multiple consecutive
3980
 * hyphens in the originally passed $id are replaced with a single hyphen.
3981
 *
3982
 * @param $id
3983
 *   The ID to clean.
3984
 *
3985
 * @return
3986
 *   The cleaned ID.
3987
 */
3988
function drupal_html_id($id) {
3989
  // If this is an Ajax request, then content returned by this page request will
3990
  // be merged with content already on the base page. The HTML IDs must be
3991
  // unique for the fully merged content. Therefore, initialize $seen_ids to
3992
  // take into account IDs that are already in use on the base page.
3993
  static $drupal_static_fast;
3994
  if (!isset($drupal_static_fast['seen_ids_init'])) {
3995
    $drupal_static_fast['seen_ids_init'] = &drupal_static(__FUNCTION__ . ':init');
3996
  }
3997
  $seen_ids_init = &$drupal_static_fast['seen_ids_init'];
3998
  if (!isset($seen_ids_init)) {
3999
    // Ideally, Drupal would provide an API to persist state information about
4000
    // prior page requests in the database, and we'd be able to add this
4001
    // function's $seen_ids static variable to that state information in order
4002
    // to have it properly initialized for this page request. However, no such
4003
    // page state API exists, so instead, ajax.js adds all of the in-use HTML
4004
    // IDs to the POST data of Ajax submissions. Direct use of $_POST is
4005
    // normally not recommended as it could open up security risks, but because
4006
    // the raw POST data is cast to a number before being returned by this
4007
    // function, this usage is safe.
4008
    if (empty($_POST['ajax_html_ids'])) {
4009
      $seen_ids_init = array();
4010
    }
4011
    else {
4012
      // This function ensures uniqueness by appending a counter to the base id
4013
      // requested by the calling function after the first occurrence of that
4014
      // requested id. $_POST['ajax_html_ids'] contains the ids as they were
4015
      // returned by this function, potentially with the appended counter, so
4016
      // we parse that to reconstruct the $seen_ids array.
4017
      if (isset($_POST['ajax_html_ids'][0]) && strpos($_POST['ajax_html_ids'][0], ',') === FALSE) {
4018
        $ajax_html_ids = $_POST['ajax_html_ids'];
4019
      }
4020
      else {
4021
        // jquery.form.js may send the server a comma-separated string as the
4022
        // first element of an array (see http://drupal.org/node/1575060), so
4023
        // we need to convert it to an array in that case.
4024
        $ajax_html_ids = explode(',', $_POST['ajax_html_ids'][0]);
4025
      }
4026
      foreach ($ajax_html_ids as $seen_id) {
4027
        // We rely on '--' being used solely for separating a base id from the
4028
        // counter, which this function ensures when returning an id.
4029
        $parts = explode('--', $seen_id, 2);
4030
        if (!empty($parts[1]) && is_numeric($parts[1])) {
4031
          list($seen_id, $i) = $parts;
4032
        }
4033
        else {
4034
          $i = 1;
4035
        }
4036
        if (!isset($seen_ids_init[$seen_id]) || ($i > $seen_ids_init[$seen_id])) {
4037
          $seen_ids_init[$seen_id] = $i;
4038
        }
4039
      }
4040
    }
4041
  }
4042
  if (!isset($drupal_static_fast['seen_ids'])) {
4043
    $drupal_static_fast['seen_ids'] = &drupal_static(__FUNCTION__, $seen_ids_init);
4044
  }
4045
  $seen_ids = &$drupal_static_fast['seen_ids'];
4046

    
4047
  $id = strtr(drupal_strtolower($id), array(' ' => '-', '_' => '-', '[' => '-', ']' => ''));
4048

    
4049
  // As defined in http://www.w3.org/TR/html4/types.html#type-name, HTML IDs can
4050
  // only contain letters, digits ([0-9]), hyphens ("-"), underscores ("_"),
4051
  // colons (":"), and periods ("."). We strip out any character not in that
4052
  // list. Note that the CSS spec doesn't allow colons or periods in identifiers
4053
  // (http://www.w3.org/TR/CSS21/syndata.html#characters), so we strip those two
4054
  // characters as well.
4055
  $id = preg_replace('/[^A-Za-z0-9\-_]/', '', $id);
4056

    
4057
  // Removing multiple consecutive hyphens.
4058
  $id = preg_replace('/\-+/', '-', $id);
4059
  // Ensure IDs are unique by appending a counter after the first occurrence.
4060
  // The counter needs to be appended with a delimiter that does not exist in
4061
  // the base ID. Requiring a unique delimiter helps ensure that we really do
4062
  // return unique IDs and also helps us re-create the $seen_ids array during
4063
  // Ajax requests.
4064
  if (isset($seen_ids[$id])) {
4065
    $id = $id . '--' . ++$seen_ids[$id];
4066
  }
4067
  else {
4068
    $seen_ids[$id] = 1;
4069
  }
4070

    
4071
  return $id;
4072
}
4073

    
4074
/**
4075
 * Provides a standard HTML class name that identifies a page region.
4076
 *
4077
 * It is recommended that template preprocess functions apply this class to any
4078
 * page region that is output by the theme (Drupal core already handles this in
4079
 * the standard template preprocess implementation). Standardizing the class
4080
 * names in this way allows modules to implement certain features, such as
4081
 * drag-and-drop or dynamic Ajax loading, in a theme-independent way.
4082
 *
4083
 * @param $region
4084
 *   The name of the page region (for example, 'page_top' or 'content').
4085
 *
4086
 * @return
4087
 *   An HTML class that identifies the region (for example, 'region-page-top'
4088
 *   or 'region-content').
4089
 *
4090
 * @see template_preprocess_region()
4091
 */
4092
function drupal_region_class($region) {
4093
  return drupal_html_class("region-$region");
4094
}
4095

    
4096
/**
4097
 * Adds a JavaScript file, setting, or inline code to the page.
4098
 *
4099
 * The behavior of this function depends on the parameters it is called with.
4100
 * Generally, it handles the addition of JavaScript to the page, either as
4101
 * reference to an existing file or as inline code. The following actions can be
4102
 * performed using this function:
4103
 * - Add a file ('file'): Adds a reference to a JavaScript file to the page.
4104
 * - Add inline JavaScript code ('inline'): Executes a piece of JavaScript code
4105
 *   on the current page by placing the code directly in the page (for example,
4106
 *   to tell the user that a new message arrived, by opening a pop up, alert
4107
 *   box, etc.). This should only be used for JavaScript that cannot be executed
4108
 *   from a file. When adding inline code, make sure that you are not relying on
4109
 *   $() being the jQuery function. Wrap your code in
4110
 *   @code (function ($) {... })(jQuery); @endcode
4111
 *   or use jQuery() instead of $().
4112
 * - Add external JavaScript ('external'): Allows the inclusion of external
4113
 *   JavaScript files that are not hosted on the local server. Note that these
4114
 *   external JavaScript references do not get aggregated when preprocessing is
4115
 *   on.
4116
 * - Add settings ('setting'): Adds settings to Drupal's global storage of
4117
 *   JavaScript settings. Per-page settings are required by some modules to
4118
 *   function properly. All settings will be accessible at Drupal.settings.
4119
 *
4120
 * Examples:
4121
 * @code
4122
 *   drupal_add_js('misc/collapse.js');
4123
 *   drupal_add_js('misc/collapse.js', 'file');
4124
 *   drupal_add_js('jQuery(document).ready(function () { alert("Hello!"); });', 'inline');
4125
 *   drupal_add_js('jQuery(document).ready(function () { alert("Hello!"); });',
4126
 *     array('type' => 'inline', 'scope' => 'footer', 'weight' => 5)
4127
 *   );
4128
 *   drupal_add_js('http://example.com/example.js', 'external');
4129
 *   drupal_add_js(array('myModule' => array('key' => 'value')), 'setting');
4130
 * @endcode
4131
 *
4132
 * Calling drupal_static_reset('drupal_add_js') will clear all JavaScript added
4133
 * so far.
4134
 *
4135
 * If JavaScript aggregation is enabled, all JavaScript files added with
4136
 * $options['preprocess'] set to TRUE will be merged into one aggregate file.
4137
 * Preprocessed inline JavaScript will not be aggregated into this single file.
4138
 * Externally hosted JavaScripts are never aggregated.
4139
 *
4140
 * The reason for aggregating the files is outlined quite thoroughly here:
4141
 * http://www.die.net/musings/page_load_time/ "Load fewer external objects. Due
4142
 * to request overhead, one bigger file just loads faster than two smaller ones
4143
 * half its size."
4144
 *
4145
 * $options['preprocess'] should be only set to TRUE when a file is required for
4146
 * all typical visitors and most pages of a site. It is critical that all
4147
 * preprocessed files are added unconditionally on every page, even if the
4148
 * files are not needed on a page. This is normally done by calling
4149
 * drupal_add_js() in a hook_init() implementation.
4150
 *
4151
 * Non-preprocessed files should only be added to the page when they are
4152
 * actually needed.
4153
 *
4154
 * @param $data
4155
 *   (optional) If given, the value depends on the $options parameter, or
4156
 *   $options['type'] if $options is passed as an associative array:
4157
 *   - 'file': Path to the file relative to base_path().
4158
 *   - 'inline': The JavaScript code that should be placed in the given scope.
4159
 *   - 'external': The absolute path to an external JavaScript file that is not
4160
 *     hosted on the local server. These files will not be aggregated if
4161
 *     JavaScript aggregation is enabled.
4162
 *   - 'setting': An associative array with configuration options. The array is
4163
 *     merged directly into Drupal.settings. All modules should wrap their
4164
 *     actual configuration settings in another variable to prevent conflicts in
4165
 *     the Drupal.settings namespace. Items added with a string key will replace
4166
 *     existing settings with that key; items with numeric array keys will be
4167
 *     added to the existing settings array.
4168
 * @param $options
4169
 *   (optional) A string defining the type of JavaScript that is being added in
4170
 *   the $data parameter ('file'/'setting'/'inline'/'external'), or an
4171
 *   associative array. JavaScript settings should always pass the string
4172
 *   'setting' only. Other types can have the following elements in the array:
4173
 *   - type: The type of JavaScript that is to be added to the page. Allowed
4174
 *     values are 'file', 'inline', 'external' or 'setting'. Defaults
4175
 *     to 'file'.
4176
 *   - scope: The location in which you want to place the script. Possible
4177
 *     values are 'header' or 'footer'. If your theme implements different
4178
 *     regions, you can also use these. Defaults to 'header'.
4179
 *   - group: A number identifying the group in which to add the JavaScript.
4180
 *     Available constants are:
4181
 *     - JS_LIBRARY: Any libraries, settings, or jQuery plugins.
4182
 *     - JS_DEFAULT: Any module-layer JavaScript.
4183
 *     - JS_THEME: Any theme-layer JavaScript.
4184
 *     The group number serves as a weight: JavaScript within a lower weight
4185
 *     group is presented on the page before JavaScript within a higher weight
4186
 *     group.
4187
 *   - every_page: For optimal front-end performance when aggregation is
4188
 *     enabled, this should be set to TRUE if the JavaScript is present on every
4189
 *     page of the website for users for whom it is present at all. This
4190
 *     defaults to FALSE. It is set to TRUE for JavaScript files that are added
4191
 *     via module and theme .info files. Modules that add JavaScript within
4192
 *     hook_init() implementations, or from other code that ensures that the
4193
 *     JavaScript is added to all website pages, should also set this flag to
4194
 *     TRUE. All JavaScript files within the same group and that have the
4195
 *     'every_page' flag set to TRUE and do not have 'preprocess' set to FALSE
4196
 *     are aggregated together into a single aggregate file, and that aggregate
4197
 *     file can be reused across a user's entire site visit, leading to faster
4198
 *     navigation between pages. However, JavaScript that is only needed on
4199
 *     pages less frequently visited, can be added by code that only runs for
4200
 *     those particular pages, and that code should not set the 'every_page'
4201
 *     flag. This minimizes the size of the aggregate file that the user needs
4202
 *     to download when first visiting the website. JavaScript without the
4203
 *     'every_page' flag is aggregated into a separate aggregate file. This
4204
 *     other aggregate file is likely to change from page to page, and each new
4205
 *     aggregate file needs to be downloaded when first encountered, so it
4206
 *     should be kept relatively small by ensuring that most commonly needed
4207
 *     JavaScript is added to every page.
4208
 *   - weight: A number defining the order in which the JavaScript is added to
4209
 *     the page relative to other JavaScript with the same 'scope', 'group',
4210
 *     and 'every_page' value. In some cases, the order in which the JavaScript
4211
 *     is presented on the page is very important. jQuery, for example, must be
4212
 *     added to the page before any jQuery code is run, so jquery.js uses the
4213
 *     JS_LIBRARY group and a weight of -20, jquery.once.js (a library drupal.js
4214
 *     depends on) uses the JS_LIBRARY group and a weight of -19, drupal.js uses
4215
 *     the JS_LIBRARY group and a weight of -1, other libraries use the
4216
 *     JS_LIBRARY group and a weight of 0 or higher, and all other scripts use
4217
 *     one of the other group constants. The exact ordering of JavaScript is as
4218
 *     follows:
4219
 *     - First by scope, with 'header' first, 'footer' last, and any other
4220
 *       scopes provided by a custom theme coming in between, as determined by
4221
 *       the theme.
4222
 *     - Then by group.
4223
 *     - Then by the 'every_page' flag, with TRUE coming before FALSE.
4224
 *     - Then by weight.
4225
 *     - Then by the order in which the JavaScript was added. For example, all
4226
 *       else being the same, JavaScript added by a call to drupal_add_js() that
4227
 *       happened later in the page request gets added to the page after one for
4228
 *       which drupal_add_js() happened earlier in the page request.
4229
 *   - requires_jquery: Set this to FALSE if the JavaScript you are adding does
4230
 *     not have a dependency on jQuery. Defaults to TRUE, except for JavaScript
4231
 *     settings where it defaults to FALSE. This is used on sites that have the
4232
 *     'javascript_always_use_jquery' variable set to FALSE; on those sites, if
4233
 *     all the JavaScript added to the page by drupal_add_js() does not have a
4234
 *     dependency on jQuery, then for improved front-end performance Drupal
4235
 *     will not add jQuery and related libraries and settings to the page.
4236
 *   - defer: If set to TRUE, the defer attribute is set on the <script>
4237
 *     tag. Defaults to FALSE.
4238
 *   - cache: If set to FALSE, the JavaScript file is loaded anew on every page
4239
 *     call; in other words, it is not cached. Used only when 'type' references
4240
 *     a JavaScript file. Defaults to TRUE.
4241
 *   - preprocess: If TRUE and JavaScript aggregation is enabled, the script
4242
 *     file will be aggregated. Defaults to TRUE.
4243
 *
4244
 * @return
4245
 *   The current array of JavaScript files, settings, and in-line code,
4246
 *   including Drupal defaults, anything previously added with calls to
4247
 *   drupal_add_js(), and this function call's additions.
4248
 *
4249
 * @see drupal_get_js()
4250
 */
4251
function drupal_add_js($data = NULL, $options = NULL) {
4252
  $javascript = &drupal_static(__FUNCTION__, array());
4253
  $jquery_added = &drupal_static(__FUNCTION__ . ':jquery_added', FALSE);
4254

    
4255
  // If the $javascript variable has been reset with drupal_static_reset(),
4256
  // jQuery and related files will have been removed from the list, so set the
4257
  // variable back to FALSE to indicate they have not yet been added.
4258
  if (empty($javascript)) {
4259
    $jquery_added = FALSE;
4260
  }
4261

    
4262
  // Construct the options, taking the defaults into consideration.
4263
  if (isset($options)) {
4264
    if (!is_array($options)) {
4265
      $options = array('type' => $options);
4266
    }
4267
  }
4268
  else {
4269
    $options = array();
4270
  }
4271
  if (isset($options['type']) && $options['type'] == 'setting') {
4272
    $options += array('requires_jquery' => FALSE);
4273
  }
4274
  $options += drupal_js_defaults($data);
4275

    
4276
  // Preprocess can only be set if caching is enabled.
4277
  $options['preprocess'] = $options['cache'] ? $options['preprocess'] : FALSE;
4278

    
4279
  // Tweak the weight so that files of the same weight are included in the
4280
  // order of the calls to drupal_add_js().
4281
  $options['weight'] += count($javascript) / 1000;
4282

    
4283
  if (isset($data)) {
4284
    // Add jquery.js, drupal.js, and related files and settings if they have
4285
    // not been added yet. However, if the 'javascript_always_use_jquery'
4286
    // variable is set to FALSE (indicating that the site does not want jQuery
4287
    // automatically added on all pages) then only add it if a file or setting
4288
    // that requires jQuery is being added also.
4289
    if (!$jquery_added && (variable_get('javascript_always_use_jquery', TRUE) || $options['requires_jquery'])) {
4290
      $jquery_added = TRUE;
4291
      // url() generates the prefix using hook_url_outbound_alter(). Instead of
4292
      // running the hook_url_outbound_alter() again here, extract the prefix
4293
      // from url().
4294
      url('', array('prefix' => &$prefix));
4295
      $default_javascript = array(
4296
        'settings' => array(
4297
          'data' => array(
4298
            array('basePath' => base_path()),
4299
            array('pathPrefix' => empty($prefix) ? '' : $prefix),
4300
          ),
4301
          'type' => 'setting',
4302
          'scope' => 'header',
4303
          'group' => JS_LIBRARY,
4304
          'every_page' => TRUE,
4305
          'weight' => 0,
4306
        ),
4307
        'misc/drupal.js' => array(
4308
          'data' => 'misc/drupal.js',
4309
          'type' => 'file',
4310
          'scope' => 'header',
4311
          'group' => JS_LIBRARY,
4312
          'every_page' => TRUE,
4313
          'weight' => -1,
4314
          'requires_jquery' => TRUE,
4315
          'preprocess' => TRUE,
4316
          'cache' => TRUE,
4317
          'defer' => FALSE,
4318
        ),
4319
      );
4320
      $javascript = drupal_array_merge_deep($javascript, $default_javascript);
4321
      // Register all required libraries.
4322
      drupal_add_library('system', 'jquery', TRUE);
4323
      drupal_add_library('system', 'jquery.once', TRUE);
4324
    }
4325

    
4326
    switch ($options['type']) {
4327
      case 'setting':
4328
        // All JavaScript settings are placed in the header of the page with
4329
        // the library weight so that inline scripts appear afterwards.
4330
        $javascript['settings']['data'][] = $data;
4331
        break;
4332

    
4333
      case 'inline':
4334
        $javascript[] = $options;
4335
        break;
4336

    
4337
      default: // 'file' and 'external'
4338
        // Local and external files must keep their name as the associative key
4339
        // so the same JavaScript file is not added twice.
4340
        $javascript[$options['data']] = $options;
4341
    }
4342
  }
4343
  return $javascript;
4344
}
4345

    
4346
/**
4347
 * Constructs an array of the defaults that are used for JavaScript items.
4348
 *
4349
 * @param $data
4350
 *   (optional) The default data parameter for the JavaScript item array.
4351
 *
4352
 * @see drupal_get_js()
4353
 * @see drupal_add_js()
4354
 */
4355
function drupal_js_defaults($data = NULL) {
4356
  return array(
4357
    'type' => 'file',
4358
    'group' => JS_DEFAULT,
4359
    'every_page' => FALSE,
4360
    'weight' => 0,
4361
    'requires_jquery' => TRUE,
4362
    'scope' => 'header',
4363
    'cache' => TRUE,
4364
    'defer' => FALSE,
4365
    'preprocess' => TRUE,
4366
    'version' => NULL,
4367
    'data' => $data,
4368
  );
4369
}
4370

    
4371
/**
4372
 * Returns a themed presentation of all JavaScript code for the current page.
4373
 *
4374
 * References to JavaScript files are placed in a certain order: first, all
4375
 * 'core' files, then all 'module' and finally all 'theme' JavaScript files
4376
 * are added to the page. Then, all settings are output, followed by 'inline'
4377
 * JavaScript code. If running update.php, all preprocessing is disabled.
4378
 *
4379
 * Note that hook_js_alter(&$javascript) is called during this function call
4380
 * to allow alterations of the JavaScript during its presentation. Calls to
4381
 * drupal_add_js() from hook_js_alter() will not be added to the output
4382
 * presentation. The correct way to add JavaScript during hook_js_alter()
4383
 * is to add another element to the $javascript array, deriving from
4384
 * drupal_js_defaults(). See locale_js_alter() for an example of this.
4385
 *
4386
 * @param $scope
4387
 *   (optional) The scope for which the JavaScript rules should be returned.
4388
 *   Defaults to 'header'.
4389
 * @param $javascript
4390
 *   (optional) An array with all JavaScript code. Defaults to the default
4391
 *   JavaScript array for the given scope.
4392
 * @param $skip_alter
4393
 *   (optional) If set to TRUE, this function skips calling drupal_alter() on
4394
 *   $javascript, useful when the calling function passes a $javascript array
4395
 *   that has already been altered.
4396
 *
4397
 * @return
4398
 *   All JavaScript code segments and includes for the scope as HTML tags.
4399
 *
4400
 * @see drupal_add_js()
4401
 * @see locale_js_alter()
4402
 * @see drupal_js_defaults()
4403
 */
4404
function drupal_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALSE) {
4405
  if (!isset($javascript)) {
4406
    $javascript = drupal_add_js();
4407
  }
4408

    
4409
  // If no JavaScript items have been added, or if the only JavaScript items
4410
  // that have been added are JavaScript settings (which don't do anything
4411
  // without any JavaScript code to use them), then no JavaScript code should
4412
  // be added to the page.
4413
  if (empty($javascript) || (isset($javascript['settings']) && count($javascript) == 1)) {
4414
    return '';
4415
  }
4416

    
4417
  // Allow modules to alter the JavaScript.
4418
  if (!$skip_alter) {
4419
    drupal_alter('js', $javascript);
4420
  }
4421

    
4422
  // Filter out elements of the given scope.
4423
  $items = array();
4424
  foreach ($javascript as $key => $item) {
4425
    if ($item['scope'] == $scope) {
4426
      $items[$key] = $item;
4427
    }
4428
  }
4429

    
4430
  $output = '';
4431
  // The index counter is used to keep aggregated and non-aggregated files in
4432
  // order by weight.
4433
  $index = 1;
4434
  $processed = array();
4435
  $files = array();
4436
  $preprocess_js = (variable_get('preprocess_js', FALSE) && (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update'));
4437

    
4438
  // A dummy query-string is added to filenames, to gain control over
4439
  // browser-caching. The string changes on every update or full cache
4440
  // flush, forcing browsers to load a new copy of the files, as the
4441
  // URL changed. Files that should not be cached (see drupal_add_js())
4442
  // get REQUEST_TIME as query-string instead, to enforce reload on every
4443
  // page request.
4444
  $default_query_string = variable_get('css_js_query_string', '0');
4445

    
4446
  // For inline JavaScript to validate as XHTML, all JavaScript containing
4447
  // XHTML needs to be wrapped in CDATA. To make that backwards compatible
4448
  // with HTML 4, we need to comment out the CDATA-tag.
4449
  $embed_prefix = "\n<!--//--><![CDATA[//><!--\n";
4450
  $embed_suffix = "\n//--><!]]>\n";
4451

    
4452
  // Since JavaScript may look for arguments in the URL and act on them, some
4453
  // third-party code might require the use of a different query string.
4454
  $js_version_string = variable_get('drupal_js_version_query_string', 'v=');
4455

    
4456
  // Sort the JavaScript so that it appears in the correct order.
4457
  uasort($items, 'drupal_sort_css_js');
4458

    
4459
  // Provide the page with information about the individual JavaScript files
4460
  // used, information not otherwise available when aggregation is enabled.
4461
  $setting['ajaxPageState']['js'] = array_fill_keys(array_keys($items), 1);
4462
  unset($setting['ajaxPageState']['js']['settings']);
4463
  drupal_add_js($setting, 'setting');
4464

    
4465
  // If we're outputting the header scope, then this might be the final time
4466
  // that drupal_get_js() is running, so add the setting to this output as well
4467
  // as to the drupal_add_js() cache. If $items['settings'] doesn't exist, it's
4468
  // because drupal_get_js() was intentionally passed a $javascript argument
4469
  // stripped off settings, potentially in order to override how settings get
4470
  // output, so in this case, do not add the setting to this output.
4471
  if ($scope == 'header' && isset($items['settings'])) {
4472
    $items['settings']['data'][] = $setting;
4473
  }
4474

    
4475
  // Loop through the JavaScript to construct the rendered output.
4476
  $element = array(
4477
    '#tag' => 'script',
4478
    '#value' => '',
4479
    '#attributes' => array(
4480
      'type' => 'text/javascript',
4481
    ),
4482
  );
4483
  foreach ($items as $item) {
4484
    $query_string =  empty($item['version']) ? $default_query_string : $js_version_string . $item['version'];
4485

    
4486
    switch ($item['type']) {
4487
      case 'setting':
4488
        $js_element = $element;
4489
        $js_element['#value_prefix'] = $embed_prefix;
4490
        $js_element['#value'] = 'jQuery.extend(Drupal.settings, ' . drupal_json_encode(drupal_array_merge_deep_array($item['data'])) . ");";
4491
        $js_element['#value_suffix'] = $embed_suffix;
4492
        $output .= theme('html_tag', array('element' => $js_element));
4493
        break;
4494

    
4495
      case 'inline':
4496
        $js_element = $element;
4497
        if ($item['defer']) {
4498
          $js_element['#attributes']['defer'] = 'defer';
4499
        }
4500
        $js_element['#value_prefix'] = $embed_prefix;
4501
        $js_element['#value'] = $item['data'];
4502
        $js_element['#value_suffix'] = $embed_suffix;
4503
        $processed[$index++] = theme('html_tag', array('element' => $js_element));
4504
        break;
4505

    
4506
      case 'file':
4507
        $js_element = $element;
4508
        if (!$item['preprocess'] || !$preprocess_js) {
4509
          if ($item['defer']) {
4510
            $js_element['#attributes']['defer'] = 'defer';
4511
          }
4512
          $query_string_separator = (strpos($item['data'], '?') !== FALSE) ? '&' : '?';
4513
          $js_element['#attributes']['src'] = file_create_url($item['data']) . $query_string_separator . ($item['cache'] ? $query_string : REQUEST_TIME);
4514
          $processed[$index++] = theme('html_tag', array('element' => $js_element));
4515
        }
4516
        else {
4517
          // By increasing the index for each aggregated file, we maintain
4518
          // the relative ordering of JS by weight. We also set the key such
4519
          // that groups are split by items sharing the same 'group' value and
4520
          // 'every_page' flag. While this potentially results in more aggregate
4521
          // files, it helps make each one more reusable across a site visit,
4522
          // leading to better front-end performance of a website as a whole.
4523
          // See drupal_add_js() for details.
4524
          $key = 'aggregate_' . $item['group'] . '_' . $item['every_page'] . '_' . $index;
4525
          $processed[$key] = '';
4526
          $files[$key][$item['data']] = $item;
4527
        }
4528
        break;
4529

    
4530
      case 'external':
4531
        $js_element = $element;
4532
        // Preprocessing for external JavaScript files is ignored.
4533
        if ($item['defer']) {
4534
          $js_element['#attributes']['defer'] = 'defer';
4535
        }
4536
        $js_element['#attributes']['src'] = $item['data'];
4537
        $processed[$index++] = theme('html_tag', array('element' => $js_element));
4538
        break;
4539
    }
4540
  }
4541

    
4542
  // Aggregate any remaining JS files that haven't already been output.
4543
  if ($preprocess_js && count($files) > 0) {
4544
    foreach ($files as $key => $file_set) {
4545
      $uri = drupal_build_js_cache($file_set);
4546
      // Only include the file if was written successfully. Errors are logged
4547
      // using watchdog.
4548
      if ($uri) {
4549
        $preprocess_file = file_create_url($uri);
4550
        $js_element = $element;
4551
        $js_element['#attributes']['src'] = $preprocess_file;
4552
        $processed[$key] = theme('html_tag', array('element' => $js_element));
4553
      }
4554
    }
4555
  }
4556

    
4557
  // Keep the order of JS files consistent as some are preprocessed and others are not.
4558
  // Make sure any inline or JS setting variables appear last after libraries have loaded.
4559
  return implode('', $processed) . $output;
4560
}
4561

    
4562
/**
4563
 * Adds attachments to a render() structure.
4564
 *
4565
 * Libraries, JavaScript, CSS and other types of custom structures are attached
4566
 * to elements using the #attached property. The #attached property is an
4567
 * associative array, where the keys are the attachment types and the values are
4568
 * the attached data. For example:
4569
 * @code
4570
 * $build['#attached'] = array(
4571
 *   'js' => array(drupal_get_path('module', 'taxonomy') . '/taxonomy.js'),
4572
 *   'css' => array(drupal_get_path('module', 'taxonomy') . '/taxonomy.css'),
4573
 * );
4574
 * @endcode
4575
 *
4576
 * 'js', 'css', and 'library' are types that get special handling. For any
4577
 * other kind of attached data, the array key must be the full name of the
4578
 * callback function and each value an array of arguments. For example:
4579
 * @code
4580
 * $build['#attached']['drupal_add_http_header'] = array(
4581
 *   array('Content-Type', 'application/rss+xml; charset=utf-8'),
4582
 * );
4583
 * @endcode
4584
 *
4585
 * External 'js' and 'css' files can also be loaded. For example:
4586
 * @code
4587
 * $build['#attached']['js'] = array(
4588
 *   'http://code.jquery.com/jquery-1.4.2.min.js' => array(
4589
 *     'type' => 'external',
4590
 *   ),
4591
 * );
4592
 * @endcode
4593
 *
4594
 * @param $elements
4595
 *   The structured array describing the data being rendered.
4596
 * @param $group
4597
 *   The default group of JavaScript and CSS being added. This is only applied
4598
 *   to the stylesheets and JavaScript items that don't have an explicit group
4599
 *   assigned to them.
4600
 * @param $dependency_check
4601
 *   When TRUE, will exit if a given library's dependencies are missing. When
4602
 *   set to FALSE, will continue to add the libraries, even though one or more
4603
 *   dependencies are missing. Defaults to FALSE.
4604
 * @param $every_page
4605
 *   Set to TRUE to indicate that the attachments are added to every page on the
4606
 *   site. Only attachments with the every_page flag set to TRUE can participate
4607
 *   in JavaScript/CSS aggregation.
4608
 *
4609
 * @return
4610
 *   FALSE if there were any missing library dependencies; TRUE if all library
4611
 *   dependencies were met.
4612
 *
4613
 * @see drupal_add_library()
4614
 * @see drupal_add_js()
4615
 * @see drupal_add_css()
4616
 * @see drupal_render()
4617
 */
4618
function drupal_process_attached($elements, $group = JS_DEFAULT, $dependency_check = FALSE, $every_page = NULL) {
4619
  // Add defaults to the special attached structures that should be processed differently.
4620
  $elements['#attached'] += array(
4621
    'library' => array(),
4622
    'js' => array(),
4623
    'css' => array(),
4624
  );
4625

    
4626
  // Add the libraries first.
4627
  $success = TRUE;
4628
  foreach ($elements['#attached']['library'] as $library) {
4629
    if (drupal_add_library($library[0], $library[1], $every_page) === FALSE) {
4630
      $success = FALSE;
4631
      // Exit if the dependency is missing.
4632
      if ($dependency_check) {
4633
        return $success;
4634
      }
4635
    }
4636
  }
4637
  unset($elements['#attached']['library']);
4638

    
4639
  // Add both the JavaScript and the CSS.
4640
  // The parameters for drupal_add_js() and drupal_add_css() require special
4641
  // handling.
4642
  foreach (array('js', 'css') as $type) {
4643
    foreach ($elements['#attached'][$type] as $data => $options) {
4644
      // If the value is not an array, it's a filename and passed as first
4645
      // (and only) argument.
4646
      if (!is_array($options)) {
4647
        $data = $options;
4648
        $options = NULL;
4649
      }
4650
      // In some cases, the first parameter ($data) is an array. Arrays can't be
4651
      // passed as keys in PHP, so we have to get $data from the value array.
4652
      if (is_numeric($data)) {
4653
        $data = $options['data'];
4654
        unset($options['data']);
4655
      }
4656
      // Apply the default group if it isn't explicitly given.
4657
      if (!isset($options['group'])) {
4658
        $options['group'] = $group;
4659
      }
4660
      // Set the every_page flag if one was passed.
4661
      if (isset($every_page)) {
4662
        $options['every_page'] = $every_page;
4663
      }
4664
      call_user_func('drupal_add_' . $type, $data, $options);
4665
    }
4666
    unset($elements['#attached'][$type]);
4667
  }
4668

    
4669
  // Add additional types of attachments specified in the render() structure.
4670
  // Libraries, JavaScript and CSS have been added already, as they require
4671
  // special handling.
4672
  foreach ($elements['#attached'] as $callback => $options) {
4673
    if (function_exists($callback)) {
4674
      foreach ($elements['#attached'][$callback] as $args) {
4675
        call_user_func_array($callback, $args);
4676
      }
4677
    }
4678
  }
4679

    
4680
  return $success;
4681
}
4682

    
4683
/**
4684
 * Adds JavaScript to change the state of an element based on another element.
4685
 *
4686
 * A "state" means a certain property on a DOM element, such as "visible" or
4687
 * "checked". A state can be applied to an element, depending on the state of
4688
 * another element on the page. In general, states depend on HTML attributes and
4689
 * DOM element properties, which change due to user interaction.
4690
 *
4691
 * Since states are driven by JavaScript only, it is important to understand
4692
 * that all states are applied on presentation only, none of the states force
4693
 * any server-side logic, and that they will not be applied for site visitors
4694
 * without JavaScript support. All modules implementing states have to make
4695
 * sure that the intended logic also works without JavaScript being enabled.
4696
 *
4697
 * #states is an associative array in the form of:
4698
 * @code
4699
 * array(
4700
 *   STATE1 => CONDITIONS_ARRAY1,
4701
 *   STATE2 => CONDITIONS_ARRAY2,
4702
 *   ...
4703
 * )
4704
 * @endcode
4705
 * Each key is the name of a state to apply to the element, such as 'visible'.
4706
 * Each value is a list of conditions that denote when the state should be
4707
 * applied.
4708
 *
4709
 * Multiple different states may be specified to act on complex conditions:
4710
 * @code
4711
 * array(
4712
 *   'visible' => CONDITIONS,
4713
 *   'checked' => OTHER_CONDITIONS,
4714
 * )
4715
 * @endcode
4716
 *
4717
 * Every condition is a key/value pair, whose key is a jQuery selector that
4718
 * denotes another element on the page, and whose value is an array of
4719
 * conditions, which must bet met on that element:
4720
 * @code
4721
 * array(
4722
 *   'visible' => array(
4723
 *     JQUERY_SELECTOR => REMOTE_CONDITIONS,
4724
 *     JQUERY_SELECTOR => REMOTE_CONDITIONS,
4725
 *     ...
4726
 *   ),
4727
 * )
4728
 * @endcode
4729
 * All conditions must be met for the state to be applied.
4730
 *
4731
 * Each remote condition is a key/value pair specifying conditions on the other
4732
 * element that need to be met to apply the state to the element:
4733
 * @code
4734
 * array(
4735
 *   'visible' => array(
4736
 *     ':input[name="remote_checkbox"]' => array('checked' => TRUE),
4737
 *   ),
4738
 * )
4739
 * @endcode
4740
 *
4741
 * For example, to show a textfield only when a checkbox is checked:
4742
 * @code
4743
 * $form['toggle_me'] = array(
4744
 *   '#type' => 'checkbox',
4745
 *   '#title' => t('Tick this box to type'),
4746
 * );
4747
 * $form['settings'] = array(
4748
 *   '#type' => 'textfield',
4749
 *   '#states' => array(
4750
 *     // Only show this field when the 'toggle_me' checkbox is enabled.
4751
 *     'visible' => array(
4752
 *       ':input[name="toggle_me"]' => array('checked' => TRUE),
4753
 *     ),
4754
 *   ),
4755
 * );
4756
 * @endcode
4757
 *
4758
 * The following states may be applied to an element:
4759
 * - enabled
4760
 * - disabled
4761
 * - required
4762
 * - optional
4763
 * - visible
4764
 * - invisible
4765
 * - checked
4766
 * - unchecked
4767
 * - expanded
4768
 * - collapsed
4769
 *
4770
 * The following states may be used in remote conditions:
4771
 * - empty
4772
 * - filled
4773
 * - checked
4774
 * - unchecked
4775
 * - expanded
4776
 * - collapsed
4777
 * - value
4778
 *
4779
 * The following states exist for both elements and remote conditions, but are
4780
 * not fully implemented and may not change anything on the element:
4781
 * - relevant
4782
 * - irrelevant
4783
 * - valid
4784
 * - invalid
4785
 * - touched
4786
 * - untouched
4787
 * - readwrite
4788
 * - readonly
4789
 *
4790
 * When referencing select lists and radio buttons in remote conditions, a
4791
 * 'value' condition must be used:
4792
 * @code
4793
 *   '#states' => array(
4794
 *     // Show the settings if 'bar' has been selected for 'foo'.
4795
 *     'visible' => array(
4796
 *       ':input[name="foo"]' => array('value' => 'bar'),
4797
 *     ),
4798
 *   ),
4799
 * @endcode
4800
 *
4801
 * @param $elements
4802
 *   A renderable array element having a #states property as described above.
4803
 *
4804
 * @see form_example_states_form()
4805
 */
4806
function drupal_process_states(&$elements) {
4807
  $elements['#attached']['library'][] = array('system', 'drupal.states');
4808
  $elements['#attached']['js'][] = array(
4809
    'type' => 'setting',
4810
    'data' => array('states' => array('#' . $elements['#id'] => $elements['#states'])),
4811
  );
4812
}
4813

    
4814
/**
4815
 * Adds multiple JavaScript or CSS files at the same time.
4816
 *
4817
 * A library defines a set of JavaScript and/or CSS files, optionally using
4818
 * settings, and optionally requiring another library. For example, a library
4819
 * can be a jQuery plugin, a JavaScript framework, or a CSS framework. This
4820
 * function allows modules to load a library defined/shipped by itself or a
4821
 * depending module, without having to add all files of the library separately.
4822
 * Each library is only loaded once.
4823
 *
4824
 * @param $module
4825
 *   The name of the module that registered the library.
4826
 * @param $name
4827
 *   The name of the library to add.
4828
 * @param $every_page
4829
 *   Set to TRUE if this library is added to every page on the site. Only items
4830
 *   with the every_page flag set to TRUE can participate in aggregation.
4831
 *
4832
 * @return
4833
 *   TRUE if the library was successfully added; FALSE if the library or one of
4834
 *   its dependencies could not be added.
4835
 *
4836
 * @see drupal_get_library()
4837
 * @see hook_library()
4838
 * @see hook_library_alter()
4839
 */
4840
function drupal_add_library($module, $name, $every_page = NULL) {
4841
  $added = &drupal_static(__FUNCTION__, array());
4842

    
4843
  // Only process the library if it exists and it was not added already.
4844
  if (!isset($added[$module][$name])) {
4845
    if ($library = drupal_get_library($module, $name)) {
4846
      // Add all components within the library.
4847
      $elements['#attached'] = array(
4848
        'library' => $library['dependencies'],
4849
        'js' => $library['js'],
4850
        'css' => $library['css'],
4851
      );
4852
      $added[$module][$name] = drupal_process_attached($elements, JS_LIBRARY, TRUE, $every_page);
4853
    }
4854
    else {
4855
      // Requested library does not exist.
4856
      $added[$module][$name] = FALSE;
4857
    }
4858
  }
4859

    
4860
  return $added[$module][$name];
4861
}
4862

    
4863
/**
4864
 * Retrieves information for a JavaScript/CSS library.
4865
 *
4866
 * Library information is statically cached. Libraries are keyed by module for
4867
 * several reasons:
4868
 * - Libraries are not unique. Multiple modules might ship with the same library
4869
 *   in a different version or variant. This registry cannot (and does not
4870
 *   attempt to) prevent library conflicts.
4871
 * - Modules implementing and thereby depending on a library that is registered
4872
 *   by another module can only rely on that module's library.
4873
 * - Two (or more) modules can still register the same library and use it
4874
 *   without conflicts in case the libraries are loaded on certain pages only.
4875
 *
4876
 * @param $module
4877
 *   The name of a module that registered a library.
4878
 * @param $name
4879
 *   (optional) The name of a registered library to retrieve. By default, all
4880
 *   libraries registered by $module are returned.
4881
 *
4882
 * @return
4883
 *   The definition of the requested library, if $name was passed and it exists,
4884
 *   or FALSE if it does not exist. If no $name was passed, an associative array
4885
 *   of libraries registered by $module is returned (which may be empty).
4886
 *
4887
 * @see drupal_add_library()
4888
 * @see hook_library()
4889
 * @see hook_library_alter()
4890
 *
4891
 * @todo The purpose of drupal_get_*() is completely different to other page
4892
 *   requisite API functions; find and use a different name.
4893
 */
4894
function drupal_get_library($module, $name = NULL) {
4895
  $libraries = &drupal_static(__FUNCTION__, array());
4896

    
4897
  if (!isset($libraries[$module])) {
4898
    // Retrieve all libraries associated with the module.
4899
    $module_libraries = module_invoke($module, 'library');
4900
    if (empty($module_libraries)) {
4901
      $module_libraries = array();
4902
    }
4903
    // Allow modules to alter the module's registered libraries.
4904
    drupal_alter('library', $module_libraries, $module);
4905

    
4906
    foreach ($module_libraries as $key => $data) {
4907
      if (is_array($data)) {
4908
        // Add default elements to allow for easier processing.
4909
        $module_libraries[$key] += array('dependencies' => array(), 'js' => array(), 'css' => array());
4910
        foreach ($module_libraries[$key]['js'] as $file => $options) {
4911
          $module_libraries[$key]['js'][$file]['version'] = $module_libraries[$key]['version'];
4912
        }
4913
      }
4914
    }
4915
    $libraries[$module] = $module_libraries;
4916
  }
4917
  if (isset($name)) {
4918
    if (!isset($libraries[$module][$name])) {
4919
      $libraries[$module][$name] = FALSE;
4920
    }
4921
    return $libraries[$module][$name];
4922
  }
4923
  return $libraries[$module];
4924
}
4925

    
4926
/**
4927
 * Assists in adding the tableDrag JavaScript behavior to a themed table.
4928
 *
4929
 * Draggable tables should be used wherever an outline or list of sortable items
4930
 * needs to be arranged by an end-user. Draggable tables are very flexible and
4931
 * can manipulate the value of form elements placed within individual columns.
4932
 *
4933
 * To set up a table to use drag and drop in place of weight select-lists or in
4934
 * place of a form that contains parent relationships, the form must be themed
4935
 * into a table. The table must have an ID attribute set. If using
4936
 * theme_table(), the ID may be set as follows:
4937
 * @code
4938
 * $output = theme('table', array('header' => $header, 'rows' => $rows, 'attributes' => array('id' => 'my-module-table')));
4939
 * return $output;
4940
 * @endcode
4941
 *
4942
 * In the theme function for the form, a special class must be added to each
4943
 * form element within the same column, "grouping" them together.
4944
 *
4945
 * In a situation where a single weight column is being sorted in the table, the
4946
 * classes could be added like this (in the theme function):
4947
 * @code
4948
 * $form['my_elements'][$delta]['weight']['#attributes']['class'] = array('my-elements-weight');
4949
 * @endcode
4950
 *
4951
 * Each row of the table must also have a class of "draggable" in order to
4952
 * enable the drag handles:
4953
 * @code
4954
 * $row = array(...);
4955
 * $rows[] = array(
4956
 *   'data' => $row,
4957
 *   'class' => array('draggable'),
4958
 * );
4959
 * @endcode
4960
 *
4961
 * When tree relationships are present, the two additional classes
4962
 * 'tabledrag-leaf' and 'tabledrag-root' can be used to refine the behavior:
4963
 * - Rows with the 'tabledrag-leaf' class cannot have child rows.
4964
 * - Rows with the 'tabledrag-root' class cannot be nested under a parent row.
4965
 *
4966
 * Calling drupal_add_tabledrag() would then be written as such:
4967
 * @code
4968
 * drupal_add_tabledrag('my-module-table', 'order', 'sibling', 'my-elements-weight');
4969
 * @endcode
4970
 *
4971
 * In a more complex case where there are several groups in one column (such as
4972
 * the block regions on the admin/structure/block page), a separate subgroup
4973
 * class must also be added to differentiate the groups.
4974
 * @code
4975
 * $form['my_elements'][$region][$delta]['weight']['#attributes']['class'] = array('my-elements-weight', 'my-elements-weight-' . $region);
4976
 * @endcode
4977
 *
4978
 * $group is still 'my-element-weight', and the additional $subgroup variable
4979
 * will be passed in as 'my-elements-weight-' . $region. This also means that
4980
 * you'll need to call drupal_add_tabledrag() once for every region added.
4981
 *
4982
 * @code
4983
 * foreach ($regions as $region) {
4984
 *   drupal_add_tabledrag('my-module-table', 'order', 'sibling', 'my-elements-weight', 'my-elements-weight-' . $region);
4985
 * }
4986
 * @endcode
4987
 *
4988
 * In a situation where tree relationships are present, adding multiple
4989
 * subgroups is not necessary, because the table will contain indentations that
4990
 * provide enough information about the sibling and parent relationships. See
4991
 * theme_menu_overview_form() for an example creating a table containing parent
4992
 * relationships.
4993
 *
4994
 * Note that this function should be called from the theme layer, such as in a
4995
 * .tpl.php file, theme_ function, or in a template_preprocess function, not in
4996
 * a form declaration. Though the same JavaScript could be added to the page
4997
 * using drupal_add_js() directly, this function helps keep template files
4998
 * clean and readable. It also prevents tabledrag.js from being added twice
4999
 * accidentally.
5000
 *
5001
 * @param $table_id
5002
 *   String containing the target table's id attribute. If the table does not
5003
 *   have an id, one will need to be set, such as <table id="my-module-table">.
5004
 * @param $action
5005
 *   String describing the action to be done on the form item. Either 'match'
5006
 *   'depth', or 'order'. Match is typically used for parent relationships.
5007
 *   Order is typically used to set weights on other form elements with the same
5008
 *   group. Depth updates the target element with the current indentation.
5009
 * @param $relationship
5010
 *   String describing where the $action variable should be performed. Either
5011
 *   'parent', 'sibling', 'group', or 'self'. Parent will only look for fields
5012
 *   up the tree. Sibling will look for fields in the same group in rows above
5013
 *   and below it. Self affects the dragged row itself. Group affects the
5014
 *   dragged row, plus any children below it (the entire dragged group).
5015
 * @param $group
5016
 *   A class name applied on all related form elements for this action.
5017
 * @param $subgroup
5018
 *   (optional) If the group has several subgroups within it, this string should
5019
 *   contain the class name identifying fields in the same subgroup.
5020
 * @param $source
5021
 *   (optional) If the $action is 'match', this string should contain the class
5022
 *   name identifying what field will be used as the source value when matching
5023
 *   the value in $subgroup.
5024
 * @param $hidden
5025
 *   (optional) The column containing the field elements may be entirely hidden
5026
 *   from view dynamically when the JavaScript is loaded. Set to FALSE if the
5027
 *   column should not be hidden.
5028
 * @param $limit
5029
 *   (optional) Limit the maximum amount of parenting in this table.
5030
 * @see block-admin-display-form.tpl.php
5031
 * @see theme_menu_overview_form()
5032
 */
5033
function drupal_add_tabledrag($table_id, $action, $relationship, $group, $subgroup = NULL, $source = NULL, $hidden = TRUE, $limit = 0) {
5034
  $js_added = &drupal_static(__FUNCTION__, FALSE);
5035
  if (!$js_added) {
5036
    // Add the table drag JavaScript to the page before the module JavaScript
5037
    // to ensure that table drag behaviors are registered before any module
5038
    // uses it.
5039
    drupal_add_library('system', 'jquery.cookie');
5040
    drupal_add_js('misc/tabledrag.js', array('weight' => -1));
5041
    $js_added = TRUE;
5042
  }
5043

    
5044
  // If a subgroup or source isn't set, assume it is the same as the group.
5045
  $target = isset($subgroup) ? $subgroup : $group;
5046
  $source = isset($source) ? $source : $target;
5047
  $settings['tableDrag'][$table_id][$group][] = array(
5048
    'target' => $target,
5049
    'source' => $source,
5050
    'relationship' => $relationship,
5051
    'action' => $action,
5052
    'hidden' => $hidden,
5053
    'limit' => $limit,
5054
  );
5055
  drupal_add_js($settings, 'setting');
5056
}
5057

    
5058
/**
5059
 * Aggregates JavaScript files into a cache file in the files directory.
5060
 *
5061
 * The file name for the JavaScript cache file is generated from the hash of
5062
 * the aggregated contents of the files in $files. This forces proxies and
5063
 * browsers to download new JavaScript when the JavaScript changes.
5064
 *
5065
 * The cache file name is retrieved on a page load via a lookup variable that
5066
 * contains an associative array. The array key is the hash of the names in
5067
 * $files while the value is the cache file name. The cache file is generated
5068
 * in two cases. First, if there is no file name value for the key, which will
5069
 * happen if a new file name has been added to $files or after the lookup
5070
 * variable is emptied to force a rebuild of the cache. Second, the cache file
5071
 * is generated if it is missing on disk. Old cache files are not deleted
5072
 * immediately when the lookup variable is emptied, but are deleted after a set
5073
 * period by drupal_delete_file_if_stale(). This ensures that files referenced
5074
 * by a cached page will still be available.
5075
 *
5076
 * @param $files
5077
 *   An array of JavaScript files to aggregate and compress into one file.
5078
 *
5079
 * @return
5080
 *   The URI of the cache file, or FALSE if the file could not be saved.
5081
 */
5082
function drupal_build_js_cache($files) {
5083
  $contents = '';
5084
  $uri = '';
5085
  $map = variable_get('drupal_js_cache_files', array());
5086
  // Create a new array so that only the file names are used to create the hash.
5087
  // This prevents new aggregates from being created unnecessarily.
5088
  $js_data = array();
5089
  foreach ($files as $file) {
5090
    $js_data[] = $file['data'];
5091
  }
5092
  $key = hash('sha256', serialize($js_data));
5093
  if (isset($map[$key])) {
5094
    $uri = $map[$key];
5095
  }
5096

    
5097
  if (empty($uri) || !file_exists($uri)) {
5098
    // Build aggregate JS file.
5099
    foreach ($files as $path => $info) {
5100
      if ($info['preprocess']) {
5101
        // Append a ';' and a newline after each JS file to prevent them from running together.
5102
        $contents .= file_get_contents($path) . ";\n";
5103
      }
5104
    }
5105
    // Prefix filename to prevent blocking by firewalls which reject files
5106
    // starting with "ad*".
5107
    $filename = 'js_' . drupal_hash_base64($contents) . '.js';
5108
    // Create the js/ within the files folder.
5109
    $jspath = 'public://js';
5110
    $uri = $jspath . '/' . $filename;
5111
    // Create the JS file.
5112
    file_prepare_directory($jspath, FILE_CREATE_DIRECTORY);
5113
    if (!file_exists($uri) && !file_unmanaged_save_data($contents, $uri, FILE_EXISTS_REPLACE)) {
5114
      return FALSE;
5115
    }
5116
    // If JS gzip compression is enabled, clean URLs are enabled (which means
5117
    // that rewrite rules are working) and the zlib extension is available then
5118
    // create a gzipped version of this file. This file is served conditionally
5119
    // to browsers that accept gzip using .htaccess rules.
5120
    if (variable_get('js_gzip_compression', TRUE) && variable_get('clean_url', 0) && extension_loaded('zlib')) {
5121
      if (!file_exists($uri . '.gz') && !file_unmanaged_save_data(gzencode($contents, 9, FORCE_GZIP), $uri . '.gz', FILE_EXISTS_REPLACE)) {
5122
        return FALSE;
5123
      }
5124
    }
5125
    $map[$key] = $uri;
5126
    variable_set('drupal_js_cache_files', $map);
5127
  }
5128
  return $uri;
5129
}
5130

    
5131
/**
5132
 * Deletes old cached JavaScript files and variables.
5133
 */
5134
function drupal_clear_js_cache() {
5135
  variable_del('javascript_parsed');
5136
  variable_del('drupal_js_cache_files');
5137
  file_scan_directory('public://js', '/.*/', array('callback' => 'drupal_delete_file_if_stale'));
5138
}
5139

    
5140
/**
5141
 * Converts a PHP variable into its JavaScript equivalent.
5142
 *
5143
 * We use HTML-safe strings, with several characters escaped.
5144
 *
5145
 * @see drupal_json_decode()
5146
 * @see drupal_json_encode_helper()
5147
 * @ingroup php_wrappers
5148
 */
5149
function drupal_json_encode($var) {
5150
  // The PHP version cannot change within a request.
5151
  static $php530;
5152

    
5153
  if (!isset($php530)) {
5154
    $php530 = version_compare(PHP_VERSION, '5.3.0', '>=');
5155
  }
5156

    
5157
  if ($php530) {
5158
    // Encode <, >, ', &, and " using the json_encode() options parameter.
5159
    return json_encode($var, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT);
5160
  }
5161

    
5162
  // json_encode() escapes <, >, ', &, and " using its options parameter, but
5163
  // does not support this parameter prior to PHP 5.3.0.  Use a helper instead.
5164
  include_once DRUPAL_ROOT . '/includes/json-encode.inc';
5165
  return drupal_json_encode_helper($var);
5166
}
5167

    
5168
/**
5169
 * Converts an HTML-safe JSON string into its PHP equivalent.
5170
 *
5171
 * @see drupal_json_encode()
5172
 * @ingroup php_wrappers
5173
 */
5174
function drupal_json_decode($var) {
5175
  return json_decode($var, TRUE);
5176
}
5177

    
5178
/**
5179
 * Returns data in JSON format.
5180
 *
5181
 * This function should be used for JavaScript callback functions returning
5182
 * data in JSON format. It sets the header for JavaScript output.
5183
 *
5184
 * @param $var
5185
 *   (optional) If set, the variable will be converted to JSON and output.
5186
 */
5187
function drupal_json_output($var = NULL) {
5188
  // We are returning JSON, so tell the browser.
5189
  drupal_add_http_header('Content-Type', 'application/json');
5190

    
5191
  if (isset($var)) {
5192
    echo drupal_json_encode($var);
5193
  }
5194
}
5195

    
5196
/**
5197
 * Ensures the private key variable used to generate tokens is set.
5198
 *
5199
 * @return
5200
 *   The private key.
5201
 */
5202
function drupal_get_private_key() {
5203
  if (!($key = variable_get('drupal_private_key', 0))) {
5204
    $key = drupal_random_key();
5205
    variable_set('drupal_private_key', $key);
5206
  }
5207
  return $key;
5208
}
5209

    
5210
/**
5211
 * Generates a token based on $value, the user session, and the private key.
5212
 *
5213
 * @param $value
5214
 *   An additional value to base the token on.
5215
 *
5216
 * The generated token is based on the session ID of the current user. Normally,
5217
 * anonymous users do not have a session, so the generated token will be
5218
 * different on every page request. To generate a token for users without a
5219
 * session, manually start a session prior to calling this function.
5220
 *
5221
 * @return string
5222
 *   A 43-character URL-safe token for validation, based on the user session ID,
5223
 *   the hash salt provided from drupal_get_hash_salt(), and the
5224
 *   'drupal_private_key' configuration variable.
5225
 *
5226
 * @see drupal_get_hash_salt()
5227
 */
5228
function drupal_get_token($value = '') {
5229
  return drupal_hmac_base64($value, session_id() . drupal_get_private_key() . drupal_get_hash_salt());
5230
}
5231

    
5232
/**
5233
 * Validates a token based on $value, the user session, and the private key.
5234
 *
5235
 * @param $token
5236
 *   The token to be validated.
5237
 * @param $value
5238
 *   An additional value to base the token on.
5239
 * @param $skip_anonymous
5240
 *   Set to true to skip token validation for anonymous users.
5241
 *
5242
 * @return
5243
 *   True for a valid token, false for an invalid token. When $skip_anonymous
5244
 *   is true, the return value will always be true for anonymous users.
5245
 */
5246
function drupal_valid_token($token, $value = '', $skip_anonymous = FALSE) {
5247
  global $user;
5248
  return (($skip_anonymous && $user->uid == 0) || ($token === drupal_get_token($value)));
5249
}
5250

    
5251
function _drupal_bootstrap_full() {
5252
  static $called = FALSE;
5253

    
5254
  if ($called) {
5255
    return;
5256
  }
5257
  $called = TRUE;
5258
  require_once DRUPAL_ROOT . '/' . variable_get('path_inc', 'includes/path.inc');
5259
  require_once DRUPAL_ROOT . '/includes/theme.inc';
5260
  require_once DRUPAL_ROOT . '/includes/pager.inc';
5261
  require_once DRUPAL_ROOT . '/' . variable_get('menu_inc', 'includes/menu.inc');
5262
  require_once DRUPAL_ROOT . '/includes/tablesort.inc';
5263
  require_once DRUPAL_ROOT . '/includes/file.inc';
5264
  require_once DRUPAL_ROOT . '/includes/unicode.inc';
5265
  require_once DRUPAL_ROOT . '/includes/image.inc';
5266
  require_once DRUPAL_ROOT . '/includes/form.inc';
5267
  require_once DRUPAL_ROOT . '/includes/mail.inc';
5268
  require_once DRUPAL_ROOT . '/includes/actions.inc';
5269
  require_once DRUPAL_ROOT . '/includes/ajax.inc';
5270
  require_once DRUPAL_ROOT . '/includes/token.inc';
5271
  require_once DRUPAL_ROOT . '/includes/errors.inc';
5272

    
5273
  // Detect string handling method
5274
  unicode_check();
5275
  // Undo magic quotes
5276
  fix_gpc_magic();
5277
  // Load all enabled modules
5278
  module_load_all();
5279
  // Reset drupal_alter() and module_implements() static caches as these
5280
  // include implementations for vital modules only when called early on
5281
  // in the bootstrap.
5282
  drupal_static_reset('drupal_alter');
5283
  drupal_static_reset('module_implements');
5284
  // Make sure all stream wrappers are registered.
5285
  file_get_stream_wrappers();
5286
  // Ensure mt_rand is reseeded, to prevent random values from one page load
5287
  // being exploited to predict random values in subsequent page loads.
5288
  $seed = unpack("L", drupal_random_bytes(4));
5289
  mt_srand($seed[1]);
5290

    
5291
  $test_info = &$GLOBALS['drupal_test_info'];
5292
  if (!empty($test_info['in_child_site'])) {
5293
    // Running inside the simpletest child site, log fatal errors to test
5294
    // specific file directory.
5295
    ini_set('log_errors', 1);
5296
    ini_set('error_log', 'public://error.log');
5297
  }
5298

    
5299
  // Initialize $_GET['q'] prior to invoking hook_init().
5300
  drupal_path_initialize();
5301

    
5302
  // Let all modules take action before the menu system handles the request.
5303
  // We do not want this while running update.php.
5304
  if (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update') {
5305
    // Prior to invoking hook_init(), initialize the theme (potentially a custom
5306
    // one for this page), so that:
5307
    // - Modules with hook_init() implementations that call theme() or
5308
    //   theme_get_registry() don't initialize the incorrect theme.
5309
    // - The theme can have hook_*_alter() implementations affect page building
5310
    //   (e.g., hook_form_alter(), hook_node_view_alter(), hook_page_alter()),
5311
    //   ahead of when rendering starts.
5312
    menu_set_custom_theme();
5313
    drupal_theme_initialize();
5314
    module_invoke_all('init');
5315
  }
5316
}
5317

    
5318
/**
5319
 * Stores the current page in the cache.
5320
 *
5321
 * If page_compression is enabled, a gzipped version of the page is stored in
5322
 * the cache to avoid compressing the output on each request. The cache entry
5323
 * is unzipped in the relatively rare event that the page is requested by a
5324
 * client without gzip support.
5325
 *
5326
 * Page compression requires the PHP zlib extension
5327
 * (http://php.net/manual/ref.zlib.php).
5328
 *
5329
 * @see drupal_page_header()
5330
 */
5331
function drupal_page_set_cache() {
5332
  global $base_root;
5333

    
5334
  if (drupal_page_is_cacheable()) {
5335

    
5336
    // Check whether the current page might be compressed.
5337
    $page_compressed = variable_get('page_compression', TRUE) && extension_loaded('zlib');
5338

    
5339
    $cache = (object) array(
5340
      'cid' => $base_root . request_uri(),
5341
      'data' => array(
5342
        'path' => $_GET['q'],
5343
        'body' => ob_get_clean(),
5344
        'title' => drupal_get_title(),
5345
        'headers' => array(),
5346
        // We need to store whether page was compressed or not,
5347
        // because by the time it is read, the configuration might change.
5348
        'page_compressed' => $page_compressed,
5349
      ),
5350
      'expire' => CACHE_TEMPORARY,
5351
      'created' => REQUEST_TIME,
5352
    );
5353

    
5354
    // Restore preferred header names based on the lower-case names returned
5355
    // by drupal_get_http_header().
5356
    $header_names = _drupal_set_preferred_header_name();
5357
    foreach (drupal_get_http_header() as $name_lower => $value) {
5358
      $cache->data['headers'][$header_names[$name_lower]] = $value;
5359
      if ($name_lower == 'expires') {
5360
        // Use the actual timestamp from an Expires header if available.
5361
        $cache->expire = strtotime($value);
5362
      }
5363
    }
5364

    
5365
    if ($cache->data['body']) {
5366
      if ($page_compressed) {
5367
        $cache->data['body'] = gzencode($cache->data['body'], 9, FORCE_GZIP);
5368
      }
5369
      cache_set($cache->cid, $cache->data, 'cache_page', $cache->expire);
5370
    }
5371
    return $cache;
5372
  }
5373
}
5374

    
5375
/**
5376
 * Executes a cron run when called.
5377
 *
5378
 * Do not call this function from a test. Use $this->cronRun() instead.
5379
 *
5380
 * @return bool
5381
 *   TRUE if cron ran successfully and FALSE if cron is already running.
5382
 */
5383
function drupal_cron_run() {
5384
  // Allow execution to continue even if the request gets canceled.
5385
  @ignore_user_abort(TRUE);
5386

    
5387
  // Prevent session information from being saved while cron is running.
5388
  $original_session_saving = drupal_save_session();
5389
  drupal_save_session(FALSE);
5390

    
5391
  // Force the current user to anonymous to ensure consistent permissions on
5392
  // cron runs.
5393
  $original_user = $GLOBALS['user'];
5394
  $GLOBALS['user'] = drupal_anonymous_user();
5395

    
5396
  // Try to allocate enough time to run all the hook_cron implementations.
5397
  drupal_set_time_limit(240);
5398

    
5399
  $return = FALSE;
5400
  // Grab the defined cron queues.
5401
  $queues = module_invoke_all('cron_queue_info');
5402
  drupal_alter('cron_queue_info', $queues);
5403

    
5404
  // Try to acquire cron lock.
5405
  if (!lock_acquire('cron', 240.0)) {
5406
    // Cron is still running normally.
5407
    watchdog('cron', 'Attempting to re-run cron while it is already running.', array(), WATCHDOG_WARNING);
5408
  }
5409
  else {
5410
    // Make sure every queue exists. There is no harm in trying to recreate an
5411
    // existing queue.
5412
    foreach ($queues as $queue_name => $info) {
5413
      DrupalQueue::get($queue_name)->createQueue();
5414
    }
5415

    
5416
    // Iterate through the modules calling their cron handlers (if any):
5417
    foreach (module_implements('cron') as $module) {
5418
      // Do not let an exception thrown by one module disturb another.
5419
      try {
5420
        module_invoke($module, 'cron');
5421
      }
5422
      catch (Exception $e) {
5423
        watchdog_exception('cron', $e);
5424
      }
5425
    }
5426

    
5427
    // Record cron time.
5428
    variable_set('cron_last', REQUEST_TIME);
5429
    watchdog('cron', 'Cron run completed.', array(), WATCHDOG_NOTICE);
5430

    
5431
    // Release cron lock.
5432
    lock_release('cron');
5433

    
5434
    // Return TRUE so other functions can check if it did run successfully
5435
    $return = TRUE;
5436
  }
5437

    
5438
  foreach ($queues as $queue_name => $info) {
5439
    if (!empty($info['skip on cron'])) {
5440
      // Do not run if queue wants to skip.
5441
      continue;
5442
    }
5443
    $callback = $info['worker callback'];
5444
    $end = time() + (isset($info['time']) ? $info['time'] : 15);
5445
    $queue = DrupalQueue::get($queue_name);
5446
    while (time() < $end && ($item = $queue->claimItem())) {
5447
      try {
5448
        call_user_func($callback, $item->data);
5449
        $queue->deleteItem($item);
5450
      }
5451
      catch (Exception $e) {
5452
        // In case of exception log it and leave the item in the queue
5453
        // to be processed again later.
5454
        watchdog_exception('cron', $e);
5455
      }
5456
    }
5457
  }
5458
  // Restore the user.
5459
  $GLOBALS['user'] = $original_user;
5460
  drupal_save_session($original_session_saving);
5461