common.inc 126 KB
Newer Older
Dries's avatar
Dries committed
1
<?php
2
// $Id$
Dries's avatar
Dries committed
3

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

12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
/**
 * Return status for saving which involved creating a new item.
 */
define('SAVED_NEW', 1);

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

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

27 28 29 30 31 32 33 34
/**
 * Set content for a specified region.
 *
 * @param $region
 *   Page region the content is assigned to.
 * @param $data
 *   Content to be set.
 */
35
function drupal_set_content($region = NULL, $data = NULL) {
36 37 38 39 40 41 42 43 44 45 46 47
  static $content = array();

  if (!is_null($region) && !is_null($data)) {
    $content[$region][] = $data;
  }
  return $content;
}

/**
 * Get assigned content.
 *
 * @param $region
48 49
 *   A specified region to fetch content for. If NULL, all regions will be
 *   returned.
50 51 52
 * @param $delimiter
 *   Content to be inserted between exploded array elements.
 */
53
function drupal_get_content($region = NULL, $delimiter = ' ') {
54
  $content = drupal_set_content();
55 56
  if (isset($region)) {
    if (isset($content[$region]) && is_array($content[$region])) {
Steven Wittens's avatar
Steven Wittens committed
57
      return implode($delimiter, $content[$region]);
58
    }
59 60 61 62
  }
  else {
    foreach (array_keys($content) as $region) {
      if (is_array($content[$region])) {
Steven Wittens's avatar
Steven Wittens committed
63
        $content[$region] = implode($delimiter, $content[$region]);
64 65 66 67 68 69
      }
    }
    return $content;
  }
}

70
/**
71
 * Set the breadcrumb trail for the current page.
72
 *
73 74 75
 * @param $breadcrumb
 *   Array of links, starting with "home" and proceeding up to but not including
 *   the current page.
76
 */
77 78 79
function drupal_set_breadcrumb($breadcrumb = NULL) {
  static $stored_breadcrumb;

80
  if (!is_null($breadcrumb)) {
81 82 83 84 85
    $stored_breadcrumb = $breadcrumb;
  }
  return $stored_breadcrumb;
}

86 87 88
/**
 * Get the breadcrumb trail for the current page.
 */
89 90 91
function drupal_get_breadcrumb() {
  $breadcrumb = drupal_set_breadcrumb();

92
  if (is_null($breadcrumb)) {
93 94 95 96 97 98
    $breadcrumb = menu_get_active_breadcrumb();
  }

  return $breadcrumb;
}

Dries's avatar
Dries committed
99
/**
100
 * Add output to the head tag of the HTML page.
101
 *
102
 * This function can be called as long the headers aren't sent.
Dries's avatar
Dries committed
103 104
 */
function drupal_set_html_head($data = NULL) {
105
  static $stored_head = '';
Dries's avatar
Dries committed
106 107

  if (!is_null($data)) {
108
    $stored_head .= $data . "\n";
Dries's avatar
Dries committed
109 110 111 112
  }
  return $stored_head;
}

113 114 115
/**
 * Retrieve output to be displayed in the head tag of the HTML page.
 */
Dries's avatar
Dries committed
116
function drupal_get_html_head() {
117
  $output = "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n";
Dries's avatar
Dries committed
118 119 120
  return $output . drupal_set_html_head();
}

121
/**
122
 * Reset the static variable which holds the aliases mapped for this request.
123
 */
124 125
function drupal_clear_path_cache() {
  drupal_lookup_path('wipe');
126
}
127

Dries's avatar
Dries committed
128
/**
129
 * Set an HTTP response header for the current page.
130
 *
131
 * Note: When sending a Content-Type header, always include a 'charset' type,
132
 * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS).
Dries's avatar
Dries committed
133 134
 */
function drupal_set_header($header = NULL) {
135
  // We use an array to guarantee there are no leading or trailing delimiters.
136
  // Otherwise, header('') could get called when serving the page later, which
137 138
  // ends HTTP headers prematurely on some PHP versions.
  static $stored_headers = array();
Dries's avatar
Dries committed
139

140
  if (strlen($header)) {
Dries's avatar
Dries committed
141
    header($header);
142
    $stored_headers[] = $header;
Dries's avatar
Dries committed
143
  }
144
  return implode("\n", $stored_headers);
Dries's avatar
Dries committed
145 146
}

147 148 149
/**
 * Get the HTTP response headers for the current page.
 */
Dries's avatar
Dries committed
150 151 152 153
function drupal_get_headers() {
  return drupal_set_header();
}

154
/**
155 156
 * Add a feed URL for the current page.
 *
157 158
 * This function can be called as long the HTML header hasn't been sent.
 *
159
 * @param $url
160
 *   A url for the feed.
161
 * @param $title
162
 *   The title of the feed.
163
 */
164
function drupal_add_feed($url = NULL, $title = '') {
165 166
  static $stored_feed_links = array();

167
  if (!is_null($url) && !isset($stored_feed_links[$url])) {
168
    $stored_feed_links[$url] = theme('feed_icon', $url, $title);
169 170 171 172 173

    drupal_add_link(array('rel' => 'alternate',
                          'type' => 'application/rss+xml',
                          'title' => $title,
                          'href' => $url));
174 175 176 177 178 179 180 181
  }
  return $stored_feed_links;
}

/**
 * Get the feed URLs for the current page.
 *
 * @param $delimiter
182
 *   A delimiter to split feeds by.
183 184 185 186 187 188
 */
function drupal_get_feeds($delimiter = "\n") {
  $feeds = drupal_add_feed();
  return implode($feeds, $delimiter);
}

189 190 191
/**
 * @name HTTP handling
 * @{
192
 * Functions to properly handle HTTP responses.
193 194
 */

195 196 197 198
/**
 * Parse an array into a valid urlencoded query string.
 *
 * @param $query
199
 *   The array to be processed e.g. $_GET.
200
 * @param $exclude
201 202
 *   The array filled with keys to be excluded. Use parent[child] to exclude
 *   nested items.
203
 * @param $parent
204
 *   Should not be passed, only used in recursive calls.
205
 * @return
206
 *   An urlencoded string which can be appended to/as the URL query string.
207 208 209 210 211
 */
function drupal_query_string_encode($query, $exclude = array(), $parent = '') {
  $params = array();

  foreach ($query as $key => $value) {
212
    $key = drupal_urlencode($key);
213
    if ($parent) {
214
      $key = $parent . '[' . $key . ']';
215 216
    }

217
    if (in_array($key, $exclude)) {
218 219 220 221 222 223 224
      continue;
    }

    if (is_array($value)) {
      $params[] = drupal_query_string_encode($value, $exclude, $key);
    }
    else {
225
      $params[] = $key . '=' . drupal_urlencode($value);
226 227 228 229 230 231
    }
  }

  return implode('&', $params);
}

232
/**
233
 * Prepare a destination query string for use in combination with drupal_goto().
234
 *
235 236 237 238
 * Used to direct the user back to the referring page after completing a form.
 * By default the current URL is returned. If a destination exists in the
 * previous request, that destination is returned. As such, a destination can
 * persist across multiple pages.
239 240 241 242
 *
 * @see drupal_goto()
 */
function drupal_get_destination() {
243
  if (isset($_REQUEST['destination'])) {
244
    return 'destination=' . urlencode($_REQUEST['destination']);
245 246
  }
  else {
247 248
    // Use $_GET here to retrieve the original path in source form.
    $path = isset($_GET['q']) ? $_GET['q'] : '';
249 250
    $query = drupal_query_string_encode($_GET, array('q'));
    if ($query != '') {
251
      $path .= '?' . $query;
252
    }
253
    return 'destination=' . urlencode($path);
254 255 256
  }
}

257
/**
258
 * Send the user to a different Drupal page.
259
 *
260 261
 * This issues an on-site HTTP redirect. The function makes sure the redirected
 * URL is formatted correctly.
262
 *
263
 * Usually the redirected URL is constructed from this function's input
264
 * parameters. However you may override that behavior by setting a
265
 * destination in either the $_REQUEST-array (i.e. by using
266
 * the query string of an URI) This is used to direct the user back to
267
 * the proper page after completing a form. For example, after editing
268
 * a post on the 'admin/content/node'-page or after having logged on using the
269
 * 'user login'-block in a sidebar. The function drupal_get_destination()
270 271
 * can be used to help set the destination URL.
 *
272 273
 * Drupal will ensure that messages set by drupal_set_message() and other
 * session data are written to the database before the user is redirected.
274 275 276 277 278
 *
 * This function ends the request; use it rather than a print theme('page')
 * statement in your menu callback.
 *
 * @param $path
279
 *   A Drupal path or a full URL.
280
 * @param $query
281
 *   A query string component, if any.
282
 * @param $fragment
283
 *   A destination fragment identifier (named anchor).
284 285 286 287 288 289 290 291
 * @param $http_response_code
 *   Valid values for an actual "goto" as per RFC 2616 section 10.3 are:
 *   - 301 Moved Permanently (the recommended value for most redirects)
 *   - 302 Found (default in Drupal and PHP, sometimes used for spamming search
 *         engines)
 *   - 303 See Other
 *   - 304 Not Modified
 *   - 305 Use Proxy
292
 *   - 307 Temporary Redirect (alternative to "503 Site Down for Maintenance")
293
 *   Note: Other values are defined by RFC 2616, but are rarely used and poorly
294
 *   supported.
295
 * @see drupal_get_destination()
296
 */
297
function drupal_goto($path = '', $query = NULL, $fragment = NULL, $http_response_code = 302) {
298

299
  if (isset($_REQUEST['destination'])) {
300
    extract(parse_url(urldecode($_REQUEST['destination'])));
301 302
  }

303
  $url = url($path, array('query' => $query, 'fragment' => $fragment, 'absolute' => TRUE));
304 305
  // Remove newlines from the URL to avoid header injection attacks.
  $url = str_replace(array("\n", "\r"), '', $url);
306

307
  // Allow modules to react to the end of the page request before redirecting.
308
  // We do not want this while running update.php.
309
  if (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update') {
310 311
    module_invoke_all('exit', $url);
  }
312

313
  // Even though session_write_close() is registered as a shutdown function, we
314
  // need all session data written to the database before redirecting.
315
  session_write_close();
316

317
  header('Location: ' . $url, TRUE, $http_response_code);
318 319

  // The "Location" header sends a redirect status code to the HTTP daemon. In
320 321
  // some cases this can be wrong, so we make sure none of the code below the
  // drupal_goto() call gets executed upon redirection.
322 323 324
  exit();
}

325
/**
326
 * Generates a site offline message.
327 328
 */
function drupal_site_offline() {
329
  drupal_maintenance_theme();
330
  drupal_set_header($_SERVER['SERVER_PROTOCOL'] . ' 503 Service unavailable');
331
  drupal_set_title(t('Site offline'));
332
  print theme('maintenance_page', filter_xss_admin(variable_get('site_offline_message',
333
    t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal'))))));
334 335
}

336 337 338
/**
 * Generates a 404 error if the request can not be handled.
 */
339
function drupal_not_found() {
340
  drupal_set_header($_SERVER['SERVER_PROTOCOL'] . ' 404 Not Found');
341

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

344
  // Keep old path for reference.
345 346 347 348
  if (!isset($_REQUEST['destination'])) {
    $_REQUEST['destination'] = $_GET['q'];
  }

349
  $path = drupal_get_normal_path(variable_get('site_404', ''));
drumm's avatar
drumm committed
350
  if ($path && $path != $_GET['q']) {
351 352 353
    // Set the active item in case there are tabs to display, or other
    // dependencies on the path.
    menu_set_active_item($path);
354
    $return = menu_execute_active_handler($path);
355
  }
356

357
  if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {
drumm's avatar
drumm committed
358
    drupal_set_title(t('Page not found'));
359
    $return = t('The requested page could not be found.');
360
  }
361

362
  // To conserve CPU and bandwidth, omit the blocks.
363
  print theme('page', $return, FALSE);
364
}
365

366 367 368 369
/**
 * Generates a 403 error if the request is not allowed.
 */
function drupal_access_denied() {
370
  drupal_set_header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
371
  watchdog('access denied', check_plain($_GET['q']), NULL, WATCHDOG_WARNING);
372

373
  // Keep old path for reference.
374 375 376 377
  if (!isset($_REQUEST['destination'])) {
    $_REQUEST['destination'] = $_GET['q'];
  }

378
  $path = drupal_get_normal_path(variable_get('site_403', ''));
drumm's avatar
drumm committed
379
  if ($path && $path != $_GET['q']) {
380
    // Set the active item in case there are tabs to display or other
381 382
    // dependencies on the path.
    menu_set_active_item($path);
383
    $return = menu_execute_active_handler($path);
384
  }
385

386
  if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {
drumm's avatar
drumm committed
387 388
    drupal_set_title(t('Access denied'));
    $return = t('You are not authorized to access this page.');
389
  }
390
  print theme('page', $return);
391 392
}

393
/**
394
 * Perform an HTTP request.
395
 *
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
 * This is a flexible and powerful HTTP client implementation. Correctly handles
 * GET, POST, PUT or any other HTTP requests. Handles redirects.
 *
 * @param $url
 *   A string containing a fully qualified URI.
 * @param $headers
 *   An array containing an HTTP header => value pair.
 * @param $method
 *   A string defining the HTTP request to use.
 * @param $data
 *   A string containing data to include in the request.
 * @param $retry
 *   An integer representing how many times to retry the request in case of a
 *   redirect.
 * @return
 *   An object containing the HTTP request headers, response code, headers,
412
 *   data and redirect status.
413 414
 */
function drupal_http_request($url, $headers = array(), $method = 'GET', $data = NULL, $retry = 3) {
415
  global $db_prefix;
416
  static $self_test = FALSE;
417
  $result = new stdClass();
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
  // Try to clear the drupal_http_request_fails variable if it's set. We
  // can't tie this call to any error because there is no surefire way to
  // tell whether a request has failed, so we add the check to places where
  // some parsing has failed.
  if (!$self_test && variable_get('drupal_http_request_fails', FALSE)) {
    $self_test = TRUE;
    $works = module_invoke('system', 'check_http_request');
    $self_test = FALSE;
    if (!$works) {
      // Do not bother with further operations if we already know that we
      // have no chance.
      $result->error = t("The server can't issue HTTP requests");
      return $result;
    }
  }
433

434
  // Parse the URL and make sure we can handle the schema.
435
  $uri = @parse_url($url);
436

437 438
  if ($uri == FALSE) {
    $result->error = 'unable to parse URL';
439 440 441
    return $result;
  }

442 443
  if (!isset($uri['scheme'])) {
    $result->error = 'missing schema';
444 445 446
    return $result;
  }

447 448
  switch ($uri['scheme']) {
    case 'http':
449
      $port = isset($uri['port']) ? $uri['port'] : 80;
450
      $host = $uri['host'] . ($port != 80 ? ':' . $port : '');
451
      $fp = @fsockopen($uri['host'], $port, $errno, $errstr, 15);
452 453
      break;
    case 'https':
454
      // Note: Only works when PHP is compiled with OpenSSL support.
455
      $port = isset($uri['port']) ? $uri['port'] : 443;
456 457
      $host = $uri['host'] . ($port != 443 ? ':' . $port : '');
      $fp = @fsockopen('ssl://' . $uri['host'], $port, $errno, $errstr, 20);
458 459
      break;
    default:
460
      $result->error = 'invalid schema ' . $uri['scheme'];
461 462 463
      return $result;
  }

464
  // Make sure the socket opened properly.
465
  if (!$fp) {
466 467
    // When a network error occurs, we use a negative number so it does not
    // clash with the HTTP status codes.
468 469
    $result->code = -$errno;
    $result->error = trim($errstr);
470 471 472
    return $result;
  }

473
  // Construct the path to act on.
474 475
  $path = isset($uri['path']) ? $uri['path'] : '/';
  if (isset($uri['query'])) {
476
    $path .= '?' . $uri['query'];
477 478
  }

479
  // Create HTTP request.
480
  $defaults = array(
481
    // RFC 2616: "non-standard ports MUST, default ports MAY be included".
482 483
    // We don't add the port to prevent from breaking rewrite rules checking the
    // host that do not take into account the port number.
484
    'Host' => "Host: $host",
485
    'User-Agent' => 'User-Agent: Drupal (+http://drupal.org/)',
486
    'Content-Length' => 'Content-Length: ' . strlen($data)
487 488
  );

489 490
  // If the server url has a user then attempt to use basic authentication
  if (isset($uri['user'])) {
491
    $defaults['Authorization'] = 'Authorization: Basic ' . base64_encode($uri['user'] . (!empty($uri['pass']) ? ":" . $uri['pass'] : ''));
492 493
  }

494 495 496 497 498 499
  // If the database prefix is being used by SimpleTest to run the tests in a copied
  // database then set the user-agent header to the database prefix so that any
  // calls to other Drupal pages will run the SimpleTest prefixed database. The
  // user-agent is used to ensure that multiple testing sessions running at the
  // same time won't interfere with each other as they would if the database
  // prefix were stored statically in a file or database variable.
500 501
  if (preg_match("/simpletest\d+/", $db_prefix, $matches)) {
    $headers['User-Agent'] = $matches[0];
502 503
  }

504
  foreach ($headers as $header => $value) {
505
    $defaults[$header] = $header . ': ' . $value;
506 507
  }

508
  $request = $method . ' ' . $path . " HTTP/1.0\r\n";
509 510 511
  $request .= implode("\r\n", $defaults);
  $request .= "\r\n\r\n";
  if ($data) {
512
    $request .= $data . "\r\n";
513 514 515 516 517 518
  }
  $result->request = $request;

  fwrite($fp, $request);

  // Fetch response.
519
  $response = '';
520 521
  while (!feof($fp) && $chunk = fread($fp, 1024)) {
    $response .= $chunk;
522 523 524 525
  }
  fclose($fp);

  // Parse response.
526 527
  list($split, $result->data) = explode("\r\n\r\n", $response, 2);
  $split = preg_split("/\r\n|\n|\r/", $split);
528

529
  list($protocol, $code, $text) = explode(' ', trim(array_shift($split)), 3);
530 531 532
  $result->headers = array();

  // Parse headers.
533
  while ($line = trim(array_shift($split))) {
534
    list($header, $value) = explode(':', $line, 2);
535 536 537
    if (isset($result->headers[$header]) && $header == 'Set-Cookie') {
      // RFC 2109: the Set-Cookie response header comprises the token Set-
      // Cookie:, followed by a comma-separated list of one or more cookies.
538
      $result->headers[$header] .= ',' . trim($value);
539 540 541 542
    }
    else {
      $result->headers[$header] = trim($value);
    }
543 544 545 546 547 548 549 550 551
  }

  $responses = array(
    100 => 'Continue', 101 => 'Switching Protocols',
    200 => 'OK', 201 => 'Created', 202 => 'Accepted', 203 => 'Non-Authoritative Information', 204 => 'No Content', 205 => 'Reset Content', 206 => 'Partial Content',
    300 => 'Multiple Choices', 301 => 'Moved Permanently', 302 => 'Found', 303 => 'See Other', 304 => 'Not Modified', 305 => 'Use Proxy', 307 => 'Temporary Redirect',
    400 => 'Bad Request', 401 => 'Unauthorized', 402 => 'Payment Required', 403 => 'Forbidden', 404 => 'Not Found', 405 => 'Method Not Allowed', 406 => 'Not Acceptable', 407 => 'Proxy Authentication Required', 408 => 'Request Time-out', 409 => 'Conflict', 410 => 'Gone', 411 => 'Length Required', 412 => 'Precondition Failed', 413 => 'Request Entity Too Large', 414 => 'Request-URI Too Large', 415 => 'Unsupported Media Type', 416 => 'Requested range not satisfiable', 417 => 'Expectation Failed',
    500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway', 503 => 'Service Unavailable', 504 => 'Gateway Time-out', 505 => 'HTTP Version not supported'
  );
552 553
  // RFC 2616 states that all unknown HTTP codes must be treated the same as the
  // base code in their class.
554 555 556 557 558 559 560 561 562 563 564 565 566 567
  if (!isset($responses[$code])) {
    $code = floor($code / 100) * 100;
  }

  switch ($code) {
    case 200: // OK
    case 304: // Not modified
      break;
    case 301: // Moved permanently
    case 302: // Moved temporarily
    case 307: // Moved temporarily
      $location = $result->headers['Location'];

      if ($retry) {
568 569
        $result = drupal_http_request($location, $headers, $method, $data, --$retry);
        $result->redirect_code = $code;
570 571 572 573 574 575 576 577 578 579 580
      }
      $result->redirect_url = $location;

      break;
    default:
      $result->error = $text;
  }

  $result->code = $code;
  return $result;
}
581 582 583
/**
 * @} End of "HTTP handling".
 */
584

585
/**
586
 * Custom PHP error handler.
587
 *
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617
 * @param $error_level
 *   The level of the error raised.
 * @param $message
 *   The error message.
 * @param $filename
 *   The filename that the error was raised in.
 * @param $line
 *   The line number the error was raised at.
 * @param $context
 *   An array that points to the active symbol table at the point the error occurred.
 */
function _drupal_error_handler($error_level, $message, $filename, $line, $context) {
  if ($error_level & error_reporting()) {
    // All these constants are documented at http://php.net/manual/en/errorfunc.constants.php
    $types = array(
      E_ERROR => 'Error',
      E_WARNING => 'Warning',
      E_PARSE => 'Parse error',
      E_NOTICE => 'Notice',
      E_CORE_ERROR => 'Core error',
      E_CORE_WARNING => 'Core warning',
      E_COMPILE_ERROR => 'Compile error',
      E_COMPILE_WARNING => 'Compile warning',
      E_USER_ERROR => 'User error',
      E_USER_WARNING => 'User warning',
      E_USER_NOTICE => 'User notice',
      E_STRICT => 'Strict warning',
      E_RECOVERABLE_ERROR => 'Recoverable fatal error'
    );
    $backtrace = debug_backtrace();
618

619 620 621 622 623 624 625 626 627 628 629 630 631 632
    // We treat recoverable errors as fatal.
    _drupal_log_error(isset($types[$error_level]) ? $types[$error_level] : 'Unknown error', $message, $backtrace, $error_level == E_RECOVERABLE_ERROR);
  }
}

/**
 * Custom PHP exception handler.
 *
 * Uncaught exceptions are those not enclosed in a try/catch block. They are
 * always fatal: the execution of the script will stop as soon as the exception
 * handler exits.
 *
 * @param $exception
 *   The exception object that was thrown.
633
 */
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651
function _drupal_exception_handler($exception) {
  $backtrace = $exception->getTrace();
  // Add the line throwing the exception to the backtrace.
  array_unshift($backtrace, array('line' => $exception->getLine(), 'file' => $exception->getFile()));

  // For PDOException errors, we try to return the initial caller,
  // skipping internal functions of the database layer.
  if ($exception instanceof PDOException) {
    // The first element in the stack is the call, the second element gives us the caller.
    // We skip calls that occurred in one of the classes of the database layer
    // or in one of its global functions.
    $db_functions = array('db_query', 'pager_query', 'db_query_range', 'db_query_temporary', 'update_sql');
    while (($caller = $backtrace[1]) &&
         ((isset($caller['class']) && (strpos($caller['class'], 'Query') !== FALSE || strpos($caller['class'], 'Database') !== FALSE)) ||
         in_array($caller['function'], $db_functions))) {
      // We remove that call.
      array_shift($backtrace);
    }
652 653
  }

654 655 656
  // Log the message to the watchdog and return an error page to the user.
  _drupal_log_error(get_class($exception), $exception->getMessage(), $backtrace, TRUE);
}
657

658 659 660 661 662 663 664 665 666 667 668 669 670 671
/**
 * Log a PHP error or exception, display an error page in fatal cases.
 *
 * @param $type
 *   The type of the error (Error, Warning, ...).
 * @param $message
 *   The message associated to the error.
 * @param $backtrace
 *   The backtrace of function calls that led to this error.
 * @param $fatal
 *   TRUE if the error is fatal.
 */
function _drupal_log_error($type, $message, $backtrace, $fatal) {
  $caller = _drupal_get_last_caller($backtrace);
672

673 674 675 676
  // Initialize a maintenance theme early if the boostrap was not complete.
  // Do it early because drupal_set_message() triggers an init_theme().
  if ($fatal && (drupal_get_bootstrap_phase() != DRUPAL_BOOTSTRAP_FULL)) {
    unset($GLOBALS['theme']);
677 678 679
    if (!defined('MAINTENANCE_MODE')) {
      define('MAINTENANCE_MODE', 'error');
    }
680 681
    drupal_maintenance_theme();
  }
682

683 684
  // When running inside the testing framework, we relay the errors
  // to the tested site by the way of HTTP headers.
685
  if (preg_match("/^simpletest\d+/", $_SERVER['HTTP_USER_AGENT']) && !headers_sent() && !defined('SIMPLETEST_DONT_COLLECT_ERRORS')) {
686 687 688 689 690 691 692 693 694 695
    static $number = 0;
    $assertion = array(
      $message,
      $type,
      $caller
    );
    header('X-Drupal-Assertion-' . $number . ': ' . rawurlencode(serialize($assertion)));
    $number++;
  }

696 697 698 699
  // Force display of error messages in update.php.
  if (variable_get('error_level', 1) == 1 || (defined('MAINTENANCE_MODE') && MAINTENANCE_MODE == 'update')) {
    drupal_set_message(t('@type: %message in %function (line %line of %file).', array('@type' => $type, '%message' => $message, '%function' => $caller['function'], '%line' => $caller['line'], '%file' => $caller['file'])), 'error');
  }
700

701
  watchdog('php', '%type: %message in %function (line %line of %file).', array('%type' => $type, '%message' => $message, '%function' => $caller['function'], '%file' => $caller['file'], '%line' => $caller['line']), WATCHDOG_ERROR);
702

703 704 705 706 707
  if ($fatal) {
    drupal_set_header($_SERVER['SERVER_PROTOCOL'] . ' Service unavailable');
    drupal_set_title(t('Error'));
    if (drupal_get_bootstrap_phase() == DRUPAL_BOOTSTRAP_FULL) {
      print theme('page', t('The website encountered an unexpected error. Please try again later.'), FALSE);
Dries's avatar
Dries committed
708
    }
709
    else {
710
      print theme('maintenance_page', t('The website encountered an unexpected error. Please try again later.'), FALSE);
711 712
    }
    exit;
Dries's avatar
Dries committed
713 714 715
  }
}

716
/**
717
 * Gets the last caller from a backtrace.
718 719 720 721 722 723 724
 *
 * @param $backtrace
 *   A standard PHP backtrace.
 * @return
 *   An associative array with keys 'file', 'line' and 'function'.
 */
function _drupal_get_last_caller($backtrace) {
725 726 727 728 729 730
  // Errors that occur inside PHP internal functions
  // do not generate information about file and line.
  while ($backtrace && !isset($backtrace[0]['line'])) {
    array_shift($backtrace);
  }

731 732 733
  // The first trace is the call itself.
  // It gives us the line and the file of the last call.
  $call = $backtrace[0];
734

735 736 737 738 739 740 741 742 743 744 745 746 747 748 749
  // The second call give us the function where the call originated.
  if (isset($backtrace[1])) {
    if (isset($backtrace[1]['class'])) {
      $call['function'] = $backtrace[1]['class'] . $backtrace[1]['type'] . $backtrace[1]['function'] . '()';
    }
    else {
      $call['function'] = $backtrace[1]['function'] . '()';
    }
  }
  else {
    $call['function'] = 'main()';
  }
  return $call;
}

750
function _fix_gpc_magic(&$item) {
Dries's avatar
Dries committed
751
  if (is_array($item)) {
Kjartan's avatar
Kjartan committed
752 753 754
    array_walk($item, '_fix_gpc_magic');
  }
  else {
Kjartan's avatar
Kjartan committed
755
    $item = stripslashes($item);
756 757 758
  }
}

759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776
/**
 * Helper function to strip slashes from $_FILES skipping over the tmp_name keys
 * since PHP generates single backslashes for file paths on Windows systems.
 *
 * tmp_name does not have backslashes added see
 * http://php.net/manual/en/features.file-upload.php#42280
 */
function _fix_gpc_magic_files(&$item, $key) {
  if ($key != 'tmp_name') {
    if (is_array($item)) {
      array_walk($item, '_fix_gpc_magic_files');
    }
    else {
      $item = stripslashes($item);
    }
  }
}

777
/**
778
 * Fix double-escaping problems caused by "magic quotes" in some PHP installations.
779
 */
780
function fix_gpc_magic() {
781
  static $fixed = FALSE;
782
  if (!$fixed && ini_get('magic_quotes_gpc')) {
Dries's avatar
Dries committed
783 784 785 786
    array_walk($_GET, '_fix_gpc_magic');
    array_walk($_POST, '_fix_gpc_magic');
    array_walk($_COOKIE, '_fix_gpc_magic');
    array_walk($_REQUEST, '_fix_gpc_magic');
787
    array_walk($_FILES, '_fix_gpc_magic_files');
788
    $fixed = TRUE;
Dries's avatar
Dries committed
789
  }
790 791
}

792
/**
793
 * Translate strings to the page language or a given language.
794
 *
795 796
 * All human-readable text that will be displayed somewhere within a page should
 * be run through the t() function.
797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814
 *
 * Examples:
 * @code
 *   if (!$info || !$info['extension']) {
 *     form_set_error('picture_upload', t('The uploaded file was not an image.'));
 *   }
 *
 *   $form['submit'] = array(
 *     '#type' => 'submit',
 *     '#value' => t('Log in'),
 *   );
 * @endcode
 *
 * Any text within t() can be extracted by translators and changed into
 * the equivalent text in their native language.
 *
 * Special variables called "placeholders" are used to signal dynamic
 * information in a string which should not be translated. Placeholders
drumm's avatar
drumm committed
815
 * can also be used for text that may change from time to time
816 817 818 819 820 821 822 823 824 825 826 827 828
 * (such as link paths) to be changed without requiring updates to translations.
 *
 * For example:
 * @code
 *   $output = t('There are currently %members and %visitors online.', array(
 *     '%members' => format_plural($total_users, '1 user', '@count users'),
 *     '%visitors' => format_plural($guests->count, '1 guest', '@count guests')));
 * @endcode
 *
 * There are three styles of placeholders:
 * - !variable, which indicates that the text should be inserted as-is. This is
 *   useful for inserting variables into things like e-mail.
 *   @code
829
 *     $message[] = t("If you don't want to receive such e-mails, you can change your settings at !url.", array('!url' => url("user/$account->uid", array('absolute' => TRUE))));
830 831 832
 *   @endcode
 *
 * - @variable, which indicates that the text should be run through check_plain,
833
 *   to escape HTML characters. Use this for any output that's displayed within
834 835
 *   a Drupal page.
 *   @code
836
 *     drupal_set_title($title = t("@name's blog", array('@name' => $account->name)), PASS_THROUGH);
837 838
 *   @endcode
 *
839 840 841
 * - %variable, which indicates that the string should be HTML escaped and
 *   highlighted with theme_placeholder() which shows up by default as
 *   <em>emphasized</em>.
842
 *   @code
843
 *     $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name));
844 845
 *   @endcode
 *
846
 * When using t(), try to put entire sentences and strings in one t() call.
847 848 849 850
 * This makes it easier for translators, as it provides context as to what each
 * word refers to. HTML markup within translation strings is allowed, but should
 * be avoided if possible. The exception are embedded links; link titles add a
 * context for translators, so should be kept in the main string.
851
 *
852
 * Here is an example of incorrect usage of t():
853 854 855 856 857 858
 * @code
 *   $output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact')));
 * @endcode
 *
 * Here is an example of t() used correctly:
 * @code
859
 *   $output .= '<p>' . t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) . '</p>';
860 861 862 863 864 865 866 867 868 869
 * @endcode
 *
 * Also avoid escaping quotation marks wherever possible.
 *
 * Incorrect:
 * @code
 *   $output .= t('Don\'t click me.');
 * @endcode
 *
 * Correct:
870
 * @code
871
 *   $output .= t("Don't click me.");
872
 * @endcode
873
 *
874
 * @param $string
875
 *   A string containing the English string to translate.
876 877
 * @param $args
 *   An associative array of replacements to make after translation. Incidences
878
 *   of any key in this array are replaced with the corresponding value.
879 880 881 882 883
 *   Based on the first character of the key, the value is escaped and/or themed:
 *    - !variable: inserted as is
 *    - @variable: escape plain text to HTML (check_plain)
 *    - %variable: escape text and theme as a placeholder for user-submitted
 *      content (check_plain + theme_placeholder)
884
 * @param $langcode
885 886
 *   Optional language code to translate to a language other than what is used
 *   to display the page.
887 888
 * @return
 *   The translated string.
889
 */
890
function t($string, $args = array(), $langcode = NULL) {
891
  global $language;
892 893
  static $custom_strings;

894 895 896
  if (!isset($langcode)) {
    $langcode = $language->language;
  }
897

898 899 900 901
  // First, check for an array of customized strings. If present, use the array
  // *instead of* database lookups. This is a high performance way to provide a
  // handful of string replacements. See settings.php for examples.
  // Cache the $custom_strings variable to improve performance.
902
  if (!isset($custom_strings[$langcode])) {
903
    $custom_strings[$langcode] = variable_get('locale_custom_strings_' . $langcode, array());
904 905
  }
  // Custom strings work for English too, even if locale module is disabled.
906 907
  if (isset($custom_strings[$langcode][$string])) {
    $string = $custom_strings[$langcode][$string];
908 909
  }
  // Translate with locale module if enabled.
910 911
  elseif (function_exists('locale') && $langcode != 'en') {
    $string = locale($string, $langcode);
912
  }
913
  if (empty($args)) {
914
    return $string;
Kjartan's avatar
Kjartan committed
915 916
  }
  else {
917
    // Transform arguments before inserting them.
918
    foreach ($args as $key => $value) {
919 920
      switch ($key[0]) {
        case '@':
921
          // Escaped only.
922
          $args[$key] = check_plain($value);
923
          break;
924

925 926
        case '%':
        default:
927
          // Escaped and placeholder.
928 929
          $args[$key] = theme('placeholder', $value);
          break;
930

931
        case '!':
932
          // Pass-through.
933 934
      }
    }
935 936
    return strtr($string, $args);
  }
937 938
}

939
/**
940
 * @defgroup validation Input validation
941
 * @{
942
 * Functions to validate user input.
943 944
 */

945
/**
946 947 948
 * Verify the syntax of the given e-mail address.
 *
 * Empty e-mail addresses are allowed. See RFC 2822 for details.
949
 *
950
 * @param $mail
951
 *   A string containing an e-mail address.
952
 * @return
953
 *   TRUE if the address is in a valid format.
954
 */
955
function valid_email_address($mail) {
956
  return (bool)filter_var($mail, FILTER_VALIDATE_EMAIL);
957 958
}

959 960 961
/**
 * Verify the syntax of the given URL.
 *
962 963 964
 * This function should only be used on actual URLs. It should not be used for
 * Drupal menu paths, which can contain arbitrary characters.
 *
965
 * @param $url
966
 *   The URL to verify.
967
 * @param $absolute
968
 *   Whether the URL is absolute (beginning with a scheme such as "http:").
969
 * @return
970
 *   TRUE if the URL is in a valid format.
971
 */
972
function valid_url($url, $absolute = FALSE) {
973
  $allowed_characters = '[a-z0-9\/:_\-_\.\?\$,;~=#&%\+]';
974
  if ($absolute) {
975
    return (bool)preg_match("/^(http|https|ftp):\/\/" . $allowed_characters . "+$/i", $url);
976 977
  }
  else {
978
    return (bool)preg_match("/^" . $allowed_characters . "+$/i", $url);
979
  }
980 981
}

982 983 984 985
/**
 * @} End of "defgroup validation".
 */

986 987 988 989
/**
 * Register an event for the current visitor (hostname/IP) to the flood control mechanism.
 *
 * @param $name
990
 *   The name of an event.
991 992
 */
function flood_register_event($name) {
993 994 995 996 997 998 999
  db_insert('flood')
    ->fields(array(
      'event' => $name,
      'hostname' => ip_address(),
      'timestamp' => REQUEST_TIME,
    ))
    ->execute();
1000 1001 1002 1003
}

/**
 * Check if the current visitor (hostname/IP) is allowed to proceed with the specified event.
1004 1005 1006
 *
 * The user is allowed to proceed if he did not trigger the specified event more
 * than $threshold times per hour.
1007 1008 1009 1010 1011 1012
 *
 * @param $name
 *   The name of the event.
 * @param $number
 *   The maximum number of the specified event per hour (per visitor).
 * @return
1013
 *   True if the user did not exceed the hourly threshold. False otherwise.
1014 1015
 */
function flood_is_allowed($name, $threshold) {
1016 1017 1018 1019 1020 1021
  $number = db_query("SELECT COUNT(*) FROM {flood} WHERE event = :event AND hostname = :hostname AND timestamp > :timestamp", array(
    ':event' => $name,
    ':hostname' => ip_address(),
    ':timestamp' => REQUEST_TIME - 3600))
    ->fetchField();
  return ($number < $threshold);
1022 1023
}

1024 1025
function check_file($filename) {
  return is_uploaded_file($filename);
Dries's avatar
Dries committed
1026 1027
}

Dries's avatar
Dries committed
1028 1029 1030 1031
/**
 * Prepare a URL for use in an HTML attribute. Strips harmful protocols.
 */
function check_url($uri) {
1032
  return filter_xss_bad_protocol($uri, FALSE);
Dries's avatar
Dries committed
1033 1034
}

1035
/**
1036
 * @defgroup format Formatting
1037
 * @{
1038
 * Functions to format numbers, strings, dates, etc.
1039 1040
 */

1041 1042 1043 1044 1045
/**
 * Formats an RSS channel.
 *
 * Arbitrary elements may be added using the $args associative array.
 */
1046 1047 1048
function format_rss_channel($title, $link, $description, $items, $langcode = NULL, $args = array()) {
  global $language;
  $langcode = $langcode ? $langcode : $language->language;
Dries's avatar
Dries committed
1049

Dries's avatar
Dries committed
1050
  $output = "<channel>\n";
1051 1052
  $output .= ' <title>' . check_plain($title) . "</title>\n";
  $output .= ' <link>' . check_url($link) . "</link>\n";
1053 1054 1055 1056

  // The RSS 2.0 "spec" doesn't indicate HTML can be used in the description.
  // We strip all HTML tags, but need to prevent double encoding from properly
  // escaped source data (such as &amp becoming &amp;amp;).