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 157
 * Add a feed URL for the current page.
 *
 * @param $url
158
 *   A url for the feed.
159
 * @param $title
160
 *   The title of the feed.
161
 */
162
function drupal_add_feed($url = NULL, $title = '') {
163 164
  static $stored_feed_links = array();

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

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

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

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

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

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

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

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

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

230
/**
231
 * Prepare a destination query string for use in combination with drupal_goto().
232
 *
233 234 235 236
 * 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.
237 238 239 240
 *
 * @see drupal_goto()
 */
function drupal_get_destination() {
241
  if (isset($_REQUEST['destination'])) {
242
    return 'destination=' . urlencode($_REQUEST['destination']);
243 244
  }
  else {
245 246
    // Use $_GET here to retrieve the original path in source form.
    $path = isset($_GET['q']) ? $_GET['q'] : '';
247 248
    $query = drupal_query_string_encode($_GET, array('q'));
    if ($query != '') {
249
      $path .= '?' . $query;
250
    }
251
    return 'destination=' . urlencode($path);
252 253 254
  }
}

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

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

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

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

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

315
  header('Location: ' . $url, TRUE, $http_response_code);
316 317

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

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

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

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

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

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

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

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

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

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

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

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

391
/**
392
 * Perform an HTTP request.
393
 *
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
 * 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,
410
 *   data and redirect status.
411 412
 */
function drupal_http_request($url, $headers = array(), $method = 'GET', $data = NULL, $retry = 3) {
413
  global $db_prefix;
414
  static $self_test = FALSE;
415
  $result = new stdClass();
416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
  // 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;
    }
  }
431

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

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

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

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

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

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

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

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

492 493 494 495 496 497 498 499 500 501
  // 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;
  }

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

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

  fwrite($fp, $request);

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

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

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

  // Parse headers.
531
  while ($line = trim(array_shift($split))) {
532
    list($header, $value) = explode(':', $line, 2);
533 534 535
    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.
536
      $result->headers[$header] .= ',' . trim($value);
537 538 539 540
    }
    else {
      $result->headers[$header] = trim($value);
    }
541 542 543 544 545 546 547 548 549
  }

  $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'
  );
550 551
  // RFC 2616 states that all unknown HTTP codes must be treated the same as the
  // base code in their class.
552 553 554 555 556 557 558 559 560 561 562 563 564 565
  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) {
566 567
        $result = drupal_http_request($location, $headers, $method, $data, --$retry);
        $result->redirect_code = $code;
568 569 570 571 572 573 574 575 576 577 578
      }
      $result->redirect_url = $location;

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

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

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

Gábor Hojtsy's avatar
Gábor Hojtsy committed
597
  if ($errno & (E_ALL)) {
598
    $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');
599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618

    // 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;
        }
      }
    }

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

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

626
    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
627 628 629
  }
}

630 631 632 633 634 635 636 637 638 639
/**
 * 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) {
640 641 642 643 644 645
  // Errors that occur inside PHP internal functions
  // do not generate information about file and line.
  while ($backtrace && !isset($backtrace[0]['line'])) {
    array_shift($backtrace);
  }

646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664
  // 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;
}

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

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

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

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

809 810
  $langcode = isset($langcode) ? $langcode : $language->language;

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

838 839
        case '%':
        default:
840
          // Escaped and placeholder.
841 842
          $args[$key] = theme('placeholder', $value);
          break;
843

844
        case '!':
845
          // Pass-through.
846 847
      }
    }
848 849
    return strtr($string, $args);
  }
850 851
}

852
/**
853
 * @defgroup validation Input validation
854
 * @{
855
 * Functions to validate user input.
856 857
 */

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

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

895 896 897 898
/**
 * @} End of "defgroup validation".
 */

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

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

927 928
function check_file($filename) {
  return is_uploaded_file($filename);
Dries's avatar
Dries committed
929 930
}

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

938
/**
939
 * @defgroup format Formatting
940
 * @{
941
 * Functions to format numbers, strings, dates, etc.
942 943
 */

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

Dries's avatar
Dries committed
953
  $output = "<channel>\n";
954 955
  $output .= ' <title>' . check_plain($title) . "</title>\n";
  $output .= ' <link>' . check_url($link) . "</link>\n";
956 957 958 959

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

  return $output;
}

969 970 971 972 973
/**
 * Format a single RSS item.
 *
 * Arbitrary elements may be added using the $args associative array.
 */
Dries's avatar
Dries committed
974
function format_rss_item($title, $link, $description, $args = array()) {
Dries's avatar
Dries committed
975
  $output = "<item>\n";
976 977 978
  $output .= ' <title>' . check_plain($title) . "</title>\n";
  $output .= ' <link>' . check_url($link) . "</link>\n";
  $output .= ' <description>' . check_plain($description) . "</description>\n";
979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999
  $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) {
1000
  $output = '';
1001 1002
  foreach ($array as $key => $value) {
    if (is_numeric($key)) {
1003
      if ($value['key']) {
1004
        $output .= ' <' . $value['key'];
1005
        if (isset($value['attributes']) && is_array($value['attributes'])) {
1006 1007 1008
          $output .= drupal_attributes($value['attributes']);
        }

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

1024
/**
1025
 * Format a string containing a count of items.
1026
 *
1027
 * This function ensures that the string is pluralized correctly. Since t() is