common.inc 120 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 for PHP 4.3 compiled with OpenSSL.
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 500 501 502 503
  // 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.
  if (preg_match("/^simpletest\d+/", $db_prefix)) {
    $headers['User-Agent'] = $db_prefix;
  }

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
 * Log errors as defined by administrator.
587
 *
588
 * Error levels:
589 590
 * - 0 = Log errors to database.
 * - 1 = Log errors to database and to screen.
591
 */
592
function drupal_error_handler($errno, $message, $filename, $line, $context) {
593 594
  // If the @ error suppression operator was used, error_reporting will have
  // been temporarily set to 0.
595 596 597 598
  if (error_reporting() == 0) {
    return;
  }

Gábor Hojtsy's avatar
Gábor Hojtsy committed
599
  if ($errno & (E_ALL)) {
600
    $types = array(1 => 'error', 2 => 'warning', 4 => 'parse error', 8 => 'notice', 16 => 'core error', 32 => 'core warning', 64 => 'compile error', 128 => 'compile warning', 256 => 'user error', 512 => 'user warning', 1024 => 'user notice', 2048 => 'strict warning', 4096 => 'recoverable fatal error');
601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620

    // For database errors, we want the line number/file name of the place that
    // the query was originally called, not _db_query().
    if (isset($context[DB_ERROR])) {
      $backtrace = array_reverse(debug_backtrace());

      // List of functions where SQL queries can originate.
      $query_functions = array('db_query', 'pager_query', 'db_query_range', 'db_query_temporary', 'update_sql');

      // Determine where query function was called, and adjust line/file
      // accordingly.
      foreach ($backtrace as $index => $function) {
        if (in_array($function['function'], $query_functions)) {
          $line = $backtrace[$index]['line'];
          $filename = $backtrace[$index]['file'];
          break;
        }
      }
    }

621
    $entry = $types[$errno] . ': ' . $message . ' in ' . $filename . ' on line ' . $line . '.';
622

623
    // Force display of error messages in update.php.
624
    if (variable_get('error_level', 1) == 1 || strstr($_SERVER['SCRIPT_NAME'], 'update.php')) {
625
      drupal_set_message($entry, 'error');
Dries's avatar
Dries committed
626
    }
627

628
    watchdog('php', '%message in %file on line %line.', array('%error' => $types[$errno], '%message' => $message, '%file' => $filename, '%line' => $line), WATCHDOG_ERROR);
Dries's avatar
Dries committed
629 630 631
  }
}

632 633 634 635 636 637 638 639 640 641
/**
 * Gets the last caller (file name and line of the call, function in which the
 * call originated) from a backtrace.
 *
 * @param $backtrace
 *   A standard PHP backtrace.
 * @return
 *   An associative array with keys 'file', 'line' and 'function'.
 */
function _drupal_get_last_caller($backtrace) {
642 643 644 645 646 647
  // Errors that occur inside PHP internal functions
  // do not generate information about file and line.
  while ($backtrace && !isset($backtrace[0]['line'])) {
    array_shift($backtrace);
  }

648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666
  // The first trace is the call itself.
  // It gives us the line and the file of the last call.
  $call = $backtrace[0];
  
  // 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;
}

667
function _fix_gpc_magic(&$item) {
Dries's avatar
Dries committed
668
  if (is_array($item)) {
Kjartan's avatar
Kjartan committed
669 670 671
    array_walk($item, '_fix_gpc_magic');
  }
  else {
Kjartan's avatar
Kjartan committed
672
    $item = stripslashes($item);
673 674 675
  }
}

676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693
/**
 * 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);
    }
  }
}

694
/**
695
 * Fix double-escaping problems caused by "magic quotes" in some PHP installations.
696
 */
697
function fix_gpc_magic() {
698
  static $fixed = FALSE;
699
  if (!$fixed && ini_get('magic_quotes_gpc')) {
Dries's avatar
Dries committed
700 701 702 703
    array_walk($_GET, '_fix_gpc_magic');
    array_walk($_POST, '_fix_gpc_magic');
    array_walk($_COOKIE, '_fix_gpc_magic');
    array_walk($_REQUEST, '_fix_gpc_magic');
704
    array_walk($_FILES, '_fix_gpc_magic_files');
705
    $fixed = TRUE;
Dries's avatar
Dries committed
706
  }
707 708
}

709
/**
710
 * Translate strings to the page language or a given language.
711
 *
712 713
 * All human-readable text that will be displayed somewhere within a page should
 * be run through the t() function.
714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731
 *
 * 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
732
 * can also be used for text that may change from time to time
733 734 735 736 737 738 739 740 741 742 743 744 745
 * (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
746
 *     $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))));
747 748 749
 *   @endcode
 *
 * - @variable, which indicates that the text should be run through check_plain,
750
 *   to escape HTML characters. Use this for any output that's displayed within
751 752 753 754 755
 *   a Drupal page.
 *   @code
 *     drupal_set_title($title = t("@name's blog", array('@name' => $account->name)));
 *   @endcode
 *
756 757 758
 * - %variable, which indicates that the string should be HTML escaped and
 *   highlighted with theme_placeholder() which shows up by default as
 *   <em>emphasized</em>.
759
 *   @code
760
 *     $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name));
761 762
 *   @endcode
 *
763
 * When using t(), try to put entire sentences and strings in one t() call.
764 765 766 767
 * 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.
768
 *
769
 * Here is an example of incorrect usage of t():
770 771 772 773 774 775
 * @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
776
 *   $output .= '<p>' . t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) . '</p>';
777 778 779 780 781 782 783 784 785 786
 * @endcode
 *
 * Also avoid escaping quotation marks wherever possible.
 *
 * Incorrect:
 * @code
 *   $output .= t('Don\'t click me.');
 * @endcode
 *
 * Correct:
787
 * @code
788
 *   $output .= t("Don't click me.");
789
 * @endcode
790
 *
791
 * @param $string
792
 *   A string containing the English string to translate.
793 794
 * @param $args
 *   An associative array of replacements to make after translation. Incidences
795
 *   of any key in this array are replaced with the corresponding value.
796 797 798 799 800
 *   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)
801
 * @param $langcode
802 803
 *   Optional language code to translate to a language other than what is used
 *   to display the page.
804 805
 * @return
 *   The translated string.
806
 */
807
function t($string, $args = array(), $langcode = NULL) {
808
  global $language;
809 810
  static $custom_strings;

811 812 813
  if (!isset($langcode)) {
    $langcode = $language->language;
  }
814

815 816 817 818
  // 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.
819
  if (!isset($custom_strings[$langcode])) {
820
    $custom_strings[$langcode] = variable_get('locale_custom_strings_' . $langcode, array());
821 822
  }
  // Custom strings work for English too, even if locale module is disabled.
823 824
  if (isset($custom_strings[$langcode][$string])) {
    $string = $custom_strings[$langcode][$string];
825 826
  }
  // Translate with locale module if enabled.
827 828
  elseif (function_exists('locale') && $langcode != 'en') {
    $string = locale($string, $langcode);
829
  }
830
  if (empty($args)) {
831
    return $string;
Kjartan's avatar
Kjartan committed
832 833
  }
  else {
834
    // Transform arguments before inserting them.
835
    foreach ($args as $key => $value) {
836 837
      switch ($key[0]) {
        case '@':
838
          // Escaped only.
839
          $args[$key] = check_plain($value);
840
          break;
841

842 843
        case '%':
        default:
844
          // Escaped and placeholder.
845 846
          $args[$key] = theme('placeholder', $value);
          break;
847

848
        case '!':
849
          // Pass-through.
850 851
      }
    }
852 853
    return strtr($string, $args);
  }
854 855
}

856
/**
857
 * @defgroup validation Input validation
858
 * @{
859
 * Functions to validate user input.
860 861
 */

862
/**
863 864 865
 * Verify the syntax of the given e-mail address.
 *
 * Empty e-mail addresses are allowed. See RFC 2822 for details.
866
 *
867
 * @param $mail
868
 *   A string containing an e-mail address.
869
 * @return
870
 *   TRUE if the address is in a valid format.
871
 */
872
function valid_email_address($mail) {
873
  return (bool)filter_var($mail, FILTER_VALIDATE_EMAIL);
874 875
}

876 877 878
/**
 * Verify the syntax of the given URL.
 *
879 880 881
 * This function should only be used on actual URLs. It should not be used for
 * Drupal menu paths, which can contain arbitrary characters.
 *
882
 * @param $url
883
 *   The URL to verify.
884
 * @param $absolute
885
 *   Whether the URL is absolute (beginning with a scheme such as "http:").
886
 * @return
887
 *   TRUE if the URL is in a valid format.
888
 */
889
function valid_url($url, $absolute = FALSE) {
890
  $allowed_characters = '[a-z0-9\/:_\-_\.\?\$,;~=#&%\+]';
891
  if ($absolute) {
892
    return (bool)preg_match("/^(http|https|ftp):\/\/" . $allowed_characters . "+$/i", $url);
893 894
  }
  else {
895
    return (bool)preg_match("/^" . $allowed_characters . "+$/i", $url);
896
  }
897 898
}

899 900 901 902
/**
 * @} End of "defgroup validation".
 */

903 904 905 906
/**
 * Register an event for the current visitor (hostname/IP) to the flood control mechanism.
 *
 * @param $name
907
 *   The name of an event.
908 909
 */
function flood_register_event($name) {
910
  db_query("INSERT INTO {flood} (event, hostname, timestamp) VALUES ('%s', '%s', %d)", $name, ip_address(), REQUEST_TIME);
911 912 913 914
}

/**
 * Check if the current visitor (hostname/IP) is allowed to proceed with the specified event.
915 916 917
 *
 * The user is allowed to proceed if he did not trigger the specified event more
 * than $threshold times per hour.
918 919 920 921 922 923
 *
 * @param $name
 *   The name of the event.
 * @param $number
 *   The maximum number of the specified event per hour (per visitor).
 * @return
924
 *   True if the user did not exceed the hourly threshold. False otherwise.
925 926
 */
function flood_is_allowed($name, $threshold) {
927
  $number = db_result(db_query("SELECT COUNT(*) FROM {flood} WHERE event = '%s' AND hostname = '%s' AND timestamp > %d", $name, ip_address(), REQUEST_TIME - 3600));
928 929 930
  return ($number < $threshold ? TRUE : FALSE);
}

931 932
function check_file($filename) {
  return is_uploaded_file($filename);
Dries's avatar
Dries committed
933 934
}

Dries's avatar
Dries committed
935 936 937 938
/**
 * Prepare a URL for use in an HTML attribute. Strips harmful protocols.
 */
function check_url($uri) {
939
  return filter_xss_bad_protocol($uri, FALSE);
Dries's avatar
Dries committed
940 941
}

942
/**
943
 * @defgroup format Formatting
944
 * @{
945
 * Functions to format numbers, strings, dates, etc.
946 947
 */

948 949 950 951 952
/**
 * Formats an RSS channel.
 *
 * Arbitrary elements may be added using the $args associative array.
 */
953 954 955
function format_rss_channel($title, $link, $description, $items, $langcode = NULL, $args = array()) {
  global $language;
  $langcode = $langcode ? $langcode : $language->language;
Dries's avatar
Dries committed
956

Dries's avatar
Dries committed
957
  $output = "<channel>\n";
958 959
  $output .= ' <title>' . check_plain($title) . "</title>\n";
  $output .= ' <link>' . check_url($link) . "</link>\n";
960 961 962 963

  // 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;).
964 965
  $output .= ' <description>' . check_plain(decode_entities(strip_tags($description))) . "</description>\n";
  $output .= ' <language>' . check_plain($langcode) . "</language>\n";
966
  $output .= format_xml_elements($args);
Dries's avatar
Dries committed
967 968 969 970 971 972
  $output .= $items;
  $output .= "</channel>\n";

  return $output;
}

973 974 975 976 977
/**
 * Format a single RSS item.
 *
 * Arbitrary elements may be added using the $args associative array.
 */
Dries's avatar
Dries committed
978
function format_rss_item($title, $link, $description, $args = array()) {
Dries's avatar
Dries committed
979
  $output = "<item>\n";
980 981 982
  $output .= ' <title>' . check_plain($title) . "</title>\n";
  $output .= ' <link>' . check_url($link) . "</link>\n";
  $output .= ' <description>' . check_plain($description) . "</description>\n";
983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003
  $output .= format_xml_elements($args);
  $output .= "</item>\n";

  return $output;
}

/**
 * Format XML elements.
 *
 * @param $array
 *   An array where each item represent an element and is either a:
 *   - (key => value) pair (<key>value</key>)
 *   - Associative array with fields:
 *     - 'key': element name
 *     - 'value': element contents
 *     - 'attributes': associative array of element attributes
 *
 * In both cases, 'value' can be a simple string, or it can be another array
 * with the same format as $array itself for nesting.
 */
function format_xml_elements($array) {
1004
  $output = '';
1005 1006
  foreach ($array as $key => $value) {
    if (is_numeric($key)) {
1007
      if ($value['key']) {
1008
        $output .= ' <' . $value['key'];
1009
        if (isset($value['attributes']) && is_array($value['attributes'])) {
1010 1011 1012
          $output .= drupal_attributes($value['attributes']);
        }

1013
        if (isset($value['value']) && $value['value'] != '') {
1014
          $output .= '>' . (is_array($value['value']) ? format_xml_elements($value['value']) : check_plain($value['value'])) . '</' . $value['key'] . ">\n";
1015 1016 1017 1018 1019 1020 1021
        }
        else {
          $output .= " />\n";
        }
      }
    }
    else {
1022
      $output .= ' <' . $key . '>' . (is_array($value) ? format_xml_elements($value) : check_plain($value)) . "</$key>\n";
1023
    }
Dries's avatar
Dries committed
1024
  }
Dries's avatar
Dries committed
1025 1026 1027
  return $output;
}

1028
/**