<?php

// $Id: common.inc,v 1.756.2.57 2009/07/01 20:51:55 goba Exp $

/**

 * @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.

 */

/**

 * 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);

/**

 * Set content for a specified region.

 *

 * @param $region

 *   Page region the content is assigned to.

 * @param $data

 *   Content to be set.

 */

function drupal_set_content($region = NULL, $data = NULL) {

  static $content = array();

  if (!is_null($region) && !is_null($data)) {

    $content[$region][] = $data;

  }

  return $content;

}

/**

 * Get assigned content.

 *

 * @param $region

 *   A specified region to fetch content for. If NULL, all regions will be

 *   returned.

 * @param $delimiter

 *   Content to be inserted between exploded array elements.

 */

function drupal_get_content($region = NULL, $delimiter = ' ') {

  $content = drupal_set_content();

  if (isset($region)) {

    if (isset($content[$region]) && is_array($content[$region])) {

      return implode($delimiter, $content[$region]);

    }

  }

  else {

    foreach (array_keys($content) as $region) {

      if (is_array($content[$region])) {

        $content[$region] = implode($delimiter, $content[$region]);

      }

    }

    return $content;

  }

}

/**

 * Set the breadcrumb trail for the current page.

 *

 * @param $breadcrumb

 *   Array of links, starting with "home" and proceeding up to but not including

 *   the current page.

 */

function drupal_set_breadcrumb($breadcrumb = NULL) {

  static $stored_breadcrumb;

  if (!is_null($breadcrumb)) {

    $stored_breadcrumb = $breadcrumb;

  }

  return $stored_breadcrumb;

}

/**

 * Get the breadcrumb trail for the current page.

 */

function drupal_get_breadcrumb() {

  $breadcrumb = drupal_set_breadcrumb();

  if (is_null($breadcrumb)) {

    $breadcrumb = menu_get_active_breadcrumb();

  }

  return $breadcrumb;

}

/**

 * Add output to the head tag of the HTML page.

 *

 * This function can be called as long the headers aren't sent.

 */

function drupal_set_html_head($data = NULL) {

  static $stored_head = '';

  if (!is_null($data)) {

    $stored_head .= $data ."\n";

  }

  return $stored_head;

}

/**

 * Retrieve output to be displayed in the head tag of the HTML page.

 */

function drupal_get_html_head() {

  $output = "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n";

  return $output . drupal_set_html_head();

}

/**

 * Reset the static variable which holds the aliases mapped for this request.

 */

function drupal_clear_path_cache() {

  drupal_lookup_path('wipe');

}

/**

 * Set an HTTP response header for the current page.

 *

 * Note: When sending a Content-Type header, always include a 'charset' type,

 * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS).

 */

function drupal_set_header($header = NULL) {

  // We use an array to guarantee there are no leading or trailing delimiters.

  // Otherwise, header('') could get called when serving the page later, which

  // ends HTTP headers prematurely on some PHP versions.

  static $stored_headers = array();

  if (strlen($header)) {

    header($header);

    $stored_headers[] = $header;

  }

  return implode("\n", $stored_headers);

}

/**

 * Get the HTTP response headers for the current page.

 */

function drupal_get_headers() {

  return drupal_set_header();

}

/**

 * Make any final alterations to the rendered xhtml.

 */

function drupal_final_markup($content) {

  // Make sure that the charset is always specified as the first element of the

  // head region to prevent encoding-based attacks.

  return preg_replace('/<head[^>]*>/i', "\$0\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />", $content, 1);

}

/**

 * Add a feed URL for the current page.

 *

 * @param $url

 *   A url for the feed.

 * @param $title

 *   The title of the feed.

 */

function drupal_add_feed($url = NULL, $title = '') {

  static $stored_feed_links = array();

  if (!is_null($url) && !isset($stored_feed_links[$url])) {

    $stored_feed_links[$url] = theme('feed_icon', $url, $title);

    drupal_add_link(array('rel' => 'alternate',

                          'type' => 'application/rss+xml',

                          'title' => $title,

                          'href' => $url));

  }

  return $stored_feed_links;

}

/**

 * Get the feed URLs for the current page.

 *

 * @param $delimiter

 *   A delimiter to split feeds by.

 */

function drupal_get_feeds($delimiter = "\n") {

  $feeds = drupal_add_feed();

  return implode($feeds, $delimiter);

}

/**

 * @name HTTP handling

 * @{

 * Functions to properly handle HTTP responses.

 */

/**

 * Parse an array into a valid urlencoded query string.

 *

 * @param $query

 *   The array to be processed e.g. $_GET.

 * @param $exclude

 *   The array filled with keys to be excluded. Use parent[child] to exclude

 *   nested items.

 * @param $parent

 *   Should not be passed, only used in recursive calls.

 * @return

 *   An urlencoded string which can be appended to/as the URL query string.

 */

function drupal_query_string_encode($query, $exclude = array(), $parent = '') {

  $params = array();

  foreach ($query as $key => $value) {

    $key = drupal_urlencode($key);

    if ($parent) {

      $key = $parent .'['. $key .']';

    }

    if (in_array($key, $exclude)) {

      continue;

    }

    if (is_array($value)) {

      $params[] = drupal_query_string_encode($value, $exclude, $key);

    }

    else {

      $params[] = $key .'='. drupal_urlencode($value);

    }

  }

  return implode('&', $params);

}

/**

 * Prepare a destination query string for use in combination with drupal_goto().

 *

 * 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.

 *

 * @see drupal_goto()

 */

function drupal_get_destination() {

  if (isset($_REQUEST['destination'])) {

    return 'destination='. urlencode($_REQUEST['destination']);

  }

  else {

    // Use $_GET here to retrieve the original path in source form.

    $path = isset($_GET['q']) ? $_GET['q'] : '';

    $query = drupal_query_string_encode($_GET, array('q'));

    if ($query != '') {

      $path .= '?'. $query;

    }

    return 'destination='. urlencode($path);

  }

}

/**

 * Send the user to a different Drupal page.

 *

 * This issues an on-site HTTP redirect. The function makes sure the redirected

 * URL is formatted correctly.

 *

 * Usually the redirected URL is constructed from this function's input

 * parameters. However you may override that behavior by setting a

 * destination in either the $_REQUEST-array (i.e. by using

 * the query string of an URI) or the $_REQUEST['edit']-array (i.e. by

 * using a hidden form field). This is used to direct the user back to

 * the proper page after completing a form. For example, after editing

 * a post on the 'admin/content/node'-page or after having logged on using the

 * 'user login'-block in a sidebar. The function drupal_get_destination()

 * can be used to help set the destination URL.

 *

 * Drupal will ensure that messages set by drupal_set_message() and other

 * session data are written to the database before the user is redirected.

 *

 * This function ends the request; use it rather than a print theme('page')

 * statement in your menu callback.

 *

 * @param $path

 *   A Drupal path or a full URL.

 * @param $query

 *   A query string component, if any.

 * @param $fragment

 *   A destination fragment identifier (named anchor).

 * @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

 *   - 307 Temporary Redirect (alternative to "503 Site Down for Maintenance")

 *   Note: Other values are defined by RFC 2616, but are rarely used and poorly

 *   supported.

 * @see drupal_get_destination()

 */

function drupal_goto($path = '', $query = NULL, $fragment = NULL, $http_response_code = 302) {

  if (isset($_REQUEST['destination'])) {

    extract(parse_url(urldecode($_REQUEST['destination'])));

  }

  else if (isset($_REQUEST['edit']['destination'])) {

    extract(parse_url(urldecode($_REQUEST['edit']['destination'])));

  }

  $url = url($path, array('query' => $query, 'fragment' => $fragment, 'absolute' => TRUE));

  // Remove newlines from the URL to avoid header injection attacks.

  $url = str_replace(array("\n", "\r"), '', $url);

  // Allow modules to react to the end of the page request before redirecting.

  // We do not want this while running update.php.

  if (!defined('MAINTENANCE_MODE') || MAINTENANCE_MODE != 'update') {

    module_invoke_all('exit', $url);

  }

  // Even though session_write_close() is registered as a shutdown function, we

  // need all session data written to the database before redirecting.

  session_write_close();

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

  // The "Location" header sends a redirect status code to the HTTP daemon. In

  // some cases this can be wrong, so we make sure none of the code below the

  // drupal_goto() call gets executed upon redirection.

  exit();

}

/**

 * Generates a site off-line message.

 */

function drupal_site_offline() {

  drupal_maintenance_theme();

  drupal_set_header('HTTP/1.1 503 Service unavailable');

  drupal_set_title(t('Site off-line'));

  print theme('maintenance_page', filter_xss_admin(variable_get('site_offline_message',

    t('@site is currently under maintenance. We should be back shortly. Thank you for your patience.', array('@site' => variable_get('site_name', 'Drupal'))))));

}

/**

 * Generates a 404 error if the request can not be handled.

 */

function drupal_not_found() {

  drupal_set_header('HTTP/1.1 404 Not Found');

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

  $path = drupal_get_normal_path(variable_get('site_404', ''));

  if ($path && $path != $_GET['q']) {

    // Set the active item in case there are tabs to display, or other

    // dependencies on the path.

    menu_set_active_item($path);

    $return = menu_execute_active_handler($path);

  }

  if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {

    drupal_set_title(t('Page not found'));

    $return = t('The requested page could not be found.');

  }

  // To conserve CPU and bandwidth, omit the blocks.

  print theme('page', $return, FALSE);

}

/**

 * Generates a 403 error if the request is not allowed.

 */

function drupal_access_denied() {

  drupal_set_header('HTTP/1.1 403 Forbidden');

  watchdog('access denied', check_plain($_GET['q']), NULL, WATCHDOG_WARNING);

  $path = drupal_get_normal_path(variable_get('site_403', ''));

  if ($path && $path != $_GET['q']) {

    // Set the active item in case there are tabs to display or other

    // dependencies on the path.

    menu_set_active_item($path);

    $return = menu_execute_active_handler($path);

  }

  if (empty($return) || $return == MENU_NOT_FOUND || $return == MENU_ACCESS_DENIED) {

    drupal_set_title(t('Access denied'));

    $return = t('You are not authorized to access this page.');

  }

  print theme('page', $return);

}

/**

 * Perform an HTTP request.

 *

 * 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,

 *   data and redirect status.

 */

function drupal_http_request($url, $headers = array(), $method = 'GET', $data = NULL, $retry = 3) {

  $result = new stdClass();

  // Parse the URL and make sure we can handle the schema.

  $uri = parse_url($url);

  if ($uri == FALSE) {

    $result->error = 'unable to parse URL';

    return $result;

  }

  if (!isset($uri['scheme'])) {

    $result->error = 'missing schema';

    return $result;

  }

  switch ($uri['scheme']) {

    case 'http':

      $port = isset($uri['port']) ? $uri['port'] : 80;

      $host = $uri['host'] . ($port != 80 ? ':'. $port : '');

      $fp = @fsockopen($uri['host'], $port, $errno, $errstr, 15);

      break;

    case 'https':

      // Note: Only works for PHP 4.3 compiled with OpenSSL.

      $port = isset($uri['port']) ? $uri['port'] : 443;

      $host = $uri['host'] . ($port != 443 ? ':'. $port : '');

      $fp = @fsockopen('ssl://'. $uri['host'], $port, $errno, $errstr, 20);

      break;

    default:

      $result->error = 'invalid schema '. $uri['scheme'];

      return $result;

  }

  // Make sure the socket opened properly.

  if (!$fp) {

    // When a network error occurs, we use a negative number so it does not

    // clash with the HTTP status codes.

    $result->code = -$errno;

    $result->error = trim($errstr);

    // Mark that this request failed. This will trigger a check of the web

    // server's ability to make outgoing HTTP requests the next time that

    // requirements checking is performed.

    // @see system_requirements()

    variable_set('drupal_http_request_fails', TRUE);

    return $result;

  }

  // Construct the path to act on.

  $path = isset($uri['path']) ? $uri['path'] : '/';

  if (isset($uri['query'])) {

    $path .= '?'. $uri['query'];

  }

  // Create HTTP request.

  $defaults = array(

    // RFC 2616: "non-standard ports MUST, default ports MAY be included".

    // We don't add the port to prevent from breaking rewrite rules checking the

    // host that do not take into account the port number.

    'Host' => "Host: $host",

    'User-Agent' => 'User-Agent: Drupal (+http://drupal.org/)',

    'Content-Length' => 'Content-Length: '. strlen($data)

  );

  // If the server url has a user then attempt to use basic authentication

  if (isset($uri['user'])) {

    $defaults['Authorization'] = 'Authorization: Basic '. base64_encode($uri['user'] . (!empty($uri['pass']) ? ":". $uri['pass'] : ''));

  }

  // 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+/", $GLOBALS['db_prefix'], $matches)) {

    $defaults['User-Agent'] = 'User-Agent: ' . $matches[0];

  }

  foreach ($headers as $header => $value) {

    $defaults[$header] = $header .': '. $value;

  }

  $request = $method .' '. $path ." HTTP/1.0\r\n";

  $request .= implode("\r\n", $defaults);

  $request .= "\r\n\r\n";

  $request .= $data;

  $result->request = $request;

  fwrite($fp, $request);

  // Fetch response.

  $response = '';

  while (!feof($fp) && $chunk = fread($fp, 1024)) {

    $response .= $chunk;

  }

  fclose($fp);

  // Parse response.

  list($split, $result->data) = explode("\r\n\r\n", $response, 2);

  $split = preg_split("/\r\n|\n|\r/", $split);

  list($protocol, $code, $text) = explode(' ', trim(array_shift($split)), 3);

  $result->headers = array();

  // Parse headers.

  while ($line = trim(array_shift($split))) {

    list($header, $value) = explode(':', $line, 2);

    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.

      $result->headers[$header] .= ','. trim($value);