<?php

/**

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

 */

/**

 * @defgroup php_wrappers PHP wrapper functions

 * @{

 * Functions that are wrappers or custom implementations of PHP functions.

 *

 * Certain PHP functions should not be used in Drupal. Instead, Drupal's

 * replacement functions should be used.

 *

 * For example, for improved or more secure UTF8-handling, or RFC-compliant

 * handling of URLs in Drupal.

 *

 * For ease of use and memorizing, all these wrapper functions use the same name

 * as the original PHP function, but prefixed with "drupal_". Beware, however,

 * that not all wrapper functions support the same arguments as the original

 * functions.

 *

 * You should always use these wrapper functions in your code.

 *

 * Wrong:

 * @code

 *   $my_substring = substr($original_string, 0, 5);

 * @endcode

 *

 * Correct:

 * @code

 *   $my_substring = drupal_substr($original_string, 0, 5);

 * @endcode

 *

 * @}

 */

/**

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

/**

 * The default group for system CSS files added to the page.

 */

define('CSS_SYSTEM', -100);

/**

 * The default group for module CSS files added to the page.

 */

define('CSS_DEFAULT', 0);

/**

 * The default group for theme CSS files added to the page.

 */

define('CSS_THEME', 100);

/**

 * The default group for JavaScript and jQuery libraries added to the page.

 */

define('JS_LIBRARY', -100);

/**

 * The default group for module JavaScript code added to the page.

 */

define('JS_DEFAULT', 0);

/**

 * The default group for theme JavaScript code added to the page.

 */

define('JS_THEME', 100);

/**

 * Error code indicating that the request exceeded the specified timeout.

 *

 * @see drupal_http_request()

 */

define('HTTP_REQUEST_TIMEOUT', -1);

/**

 * @defgroup block_caching Block Caching

 * @{

 * Constants that define each block's caching state.

 *

 * Modules specify how their blocks can be cached in their hook_block_info()

 * implementations. Caching can be turned off (DRUPAL_NO_CACHE), managed by the

 * module declaring the block (DRUPAL_CACHE_CUSTOM), or managed by the core

 * Block module. If the Block module is managing the cache, you can specify that

 * the block is the same for every page and user (DRUPAL_CACHE_GLOBAL), or that

 * it can change depending on the page (DRUPAL_CACHE_PER_PAGE) or by user

 * (DRUPAL_CACHE_PER_ROLE or DRUPAL_CACHE_PER_USER). Page and user settings can

 * be combined with a bitwise-binary or operator; for example,

 * DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE means that the block can change

 * depending on the user role or page it is on.

 *

 * The block cache is cleared in cache_clear_all(), and uses the same clearing

 * policy than page cache (node, comment, user, taxonomy added or updated...).

 * Blocks requiring more fine-grained clearing might consider disabling the

 * built-in block cache (DRUPAL_NO_CACHE) and roll their own.

 *

 * Note that user 1 is excluded from block caching.

 */

/**

 * The block should not get cached.

 *

 * This setting should be used:

 * - For simple blocks (notably those that do not perform any db query), where

 *   querying the db cache would be more expensive than directly generating the

 *   content.

 * - For blocks that change too frequently.

 */

define('DRUPAL_NO_CACHE', -1);

/**

 * The block is handling its own caching in its hook_block_view().

 *

 * This setting is useful when time based expiration is needed or a site uses a

 * node access which invalidates standard block cache.

 */

define('DRUPAL_CACHE_CUSTOM', -2);

/**

 * The block or element can change depending on the user's roles.

 *

 * This is the default setting for blocks, used when the block does not specify

 * anything.

 */

define('DRUPAL_CACHE_PER_ROLE', 0x0001);

/**

 * The block or element can change depending on the user.

 *

 * This setting can be resource-consuming for sites with large number of users,

 * and thus should only be used when DRUPAL_CACHE_PER_ROLE is not sufficient.

 */

define('DRUPAL_CACHE_PER_USER', 0x0002);

/**

 * The block or element can change depending on the page being viewed.

 */

define('DRUPAL_CACHE_PER_PAGE', 0x0004);

/**

 * The block or element is the same for every user and page that it is visible.

 */

define('DRUPAL_CACHE_GLOBAL', 0x0008);

/**

 * @} End of "defgroup block_caching".

 */

/**

 * Adds content to a specified region.

 *

 * @param $region

 *   Page region the content is added to.

 * @param $data

 *   Content to be added.

 */

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

  static $content = array();

  if (isset($region) && isset($data)) {

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

  }

  return $content;

}

/**

 * Gets assigned content for a given region.

 *

 * @param $region

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

 *   returned.

 * @param $delimiter

 *   Content to be inserted between imploded array elements.

 */

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

  $content = drupal_add_region_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;

  }

}

/**

 * Gets the name of the currently active installation profile.

 *

 * When this function is called during Drupal's initial installation process,

 * the name of the profile that's about to be installed is stored in the global

 * installation state. At all other times, the standard Drupal systems variable

 * table contains the name of the current profile, and we can call

 * variable_get() to determine what one is active.

 *

 * @return $profile

 *   The name of the installation profile.

 */

function drupal_get_profile() {

  global $install_state;

  if (isset($install_state['parameters']['profile'])) {

    $profile = $install_state['parameters']['profile'];

  }

  else {

    $profile = variable_get('install_profile', 'standard');

  }

  return $profile;

}

/**

 * Sets 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) {

  $stored_breadcrumb = &drupal_static(__FUNCTION__);

  if (isset($breadcrumb)) {

    $stored_breadcrumb = $breadcrumb;

  }

  return $stored_breadcrumb;

}

/**

 * Gets the breadcrumb trail for the current page.

 */

function drupal_get_breadcrumb() {

  $breadcrumb = drupal_set_breadcrumb();

  if (!isset($breadcrumb)) {

    $breadcrumb = menu_get_active_breadcrumb();

  }

  return $breadcrumb;

}

/**

 * Returns a string containing RDF namespace declarations for use in XML and

 * XHTML output.

 */

function drupal_get_rdf_namespaces() {

  $xml_rdf_namespaces = array();

  // Serializes the RDF namespaces in XML namespace syntax.

  if (function_exists('rdf_get_namespaces')) {

    foreach (rdf_get_namespaces() as $prefix => $uri) {

      $xml_rdf_namespaces[] = 'xmlns:' . $prefix . '="' . $uri . '"';

    }

  }

  return count($xml_rdf_namespaces) ? "\n  " . implode("\n  ", $xml_rdf_namespaces) : '';

}

/**

 * Adds output to the HEAD tag of the HTML page.

 *

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

 * arguments (or NULL for both) to retrieve the currently stored elements.

 *

 * @param $data

 *   A renderable array. If the '#type' key is not set then 'html_tag' will be

 *   added as the default '#type'.

 * @param $key

 *   A unique string key to allow implementations of hook_html_head_alter() to

 *   identify the element in $data. Required if $data is not NULL.

 *

 * @return

 *   An array of all stored HEAD elements.

 *

 * @see theme_html_tag()

 */

function drupal_add_html_head($data = NULL, $key = NULL) {

  $stored_head = &drupal_static(__FUNCTION__);

  if (!isset($stored_head)) {

    // Make sure the defaults, including Content-Type, come first.

    $stored_head = _drupal_default_html_head();

  }

  if (isset($data) && isset($key)) {

    if (!isset($data['#type'])) {

      $data['#type'] = 'html_tag';

    }

    $stored_head[$key] = $data;

  }

  return $stored_head;

}

/**

 * Returns elements that are always displayed in the HEAD tag of the HTML page.

 */

function _drupal_default_html_head() {

  // Add default elements. Make sure the Content-Type comes first because the

  // IE browser may be vulnerable to XSS via encoding attacks from any content

  // that comes before this META tag, such as a TITLE tag.

  $elements['system_meta_content_type'] = array(

    '#type' => 'html_tag',

    '#tag' => 'meta',

    '#attributes' => array(

      'http-equiv' => 'Content-Type',

      'content' => 'text/html; charset=utf-8',

    ),

    // Security: This always has to be output first.

    '#weight' => -1000,

  );

  // Show Drupal and the major version number in the META GENERATOR tag.

  // Get the major version.

  list($version, ) = explode('.', VERSION);

  $elements['system_meta_generator'] = array(

    '#type' => 'html_tag',

    '#tag' => 'meta',

    '#attributes' => array(

      'name' => 'Generator',

      'content' => 'Drupal ' . $version . ' (http://drupal.org)',

    ),

  );

  // Also send the generator in the HTTP header.

  $elements['system_meta_generator']['#attached']['drupal_add_http_header'][] = array('X-Generator', $elements['system_meta_generator']['#attributes']['content']);

  return $elements;

}

/**

 * Retrieves output to be displayed in the HEAD tag of the HTML page.

 */

function drupal_get_html_head() {

  $elements = drupal_add_html_head();

  drupal_alter('html_head', $elements);

  return drupal_render($elements);

}

/**

 * Adds a feed URL for the current page.

 *

 * This function can be called as long the HTML header hasn't been sent.

 *

 * @param $url

 *   An internal system path or a fully qualified external URL of the feed.

 * @param $title

 *   The title of the feed.

 */

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

  $stored_feed_links = &drupal_static(__FUNCTION__, array());

  if (isset($url)) {

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

    drupal_add_html_head_link(array(

      'rel' => 'alternate',

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

      'title' => $title,

      // Force the URL to be absolute, for consistency with other <link> tags

      // output by Drupal.

      'href' => url($url, array('absolute' => TRUE)),

    ));

  }

  return $stored_feed_links;

}

/**

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

}

/**

 * @defgroup http_handling HTTP handling

 * @{

 * Functions to properly handle HTTP responses.

 */

/**

 * Processes a URL query parameter array to remove unwanted elements.

 *

 * @param $query

 *   (optional) An array to be processed. Defaults to $_GET.

 * @param $exclude

 *   (optional) A list of $query array keys to remove. Use "parent[child]" to

 *   exclude nested items. Defaults to array('q').

 * @param $parent

 *   Internal use only. Used to build the $query array key for nested items.

 *

 * @return

 *   An array containing query parameters, which can be used for url().

 */

function drupal_get_query_parameters(array $query = NULL, array $exclude = array('q'), $parent = '') {

  // Set defaults, if none given.

  if (!isset($query)) {

    $query = $_GET;

  }

  // If $exclude is empty, there is nothing to filter.

  if (empty($exclude)) {

    return $query;

  }

  elseif (!$parent) {

    $exclude = array_flip($exclude);

  }

  $params = array();

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

    $string_key = ($parent ? $parent . '[' . $key . ']' : $key);

    if (isset($exclude[$string_key])) {

      continue;

    }

    if (is_array($value)) {

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

    }

    else {

      $params[$key] = $value;

    }

  }

  return $params;

}

/**

 * Splits a URL-encoded query string into an array.

 *

 * @param $query

 *   The query string to split.

 *

 * @return

 *   An array of URL decoded couples $param_name => $value.

 */

function drupal_get_query_array($query) {

  $result = array();

  if (!empty($query)) {

    foreach (explode('&', $query) as $param) {

      $param = explode('=', $param, 2);

      $result[$param[0]] = isset($param[1]) ? rawurldecode($param[1]) : '';

    }

  }

  return $result;

}

/**

 * Parses an array into a valid, rawurlencoded query string.

 *

 * This differs from http_build_query() as we need to rawurlencode() (instead of

 * urlencode()) all query parameters.

 *

 * @param $query

 *   The query parameter array to be processed, e.g. $_GET.

 * @param $parent

 *   Internal use only. Used to build the $query array key for nested items.

 *

 * @return

 *   A rawurlencoded string which can be used as or appended to the URL query

 *   string.

 *

 * @see drupal_get_query_parameters()

 * @ingroup php_wrappers

 */

function drupal_http_build_query(array $query, $parent = '') {

  $params = array();

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

    $key = $parent ? $parent . rawurlencode('[' . $key . ']') : rawurlencode($key);

    // Recurse into children.

    if (is_array($value)) {

      $params[] = drupal_http_build_query($value, $key);

    }

    // If a query parameter value is NULL, only append its key.

    elseif (!isset($value)) {

      $params[] = $key;

    }

    else {

      // For better readability of paths in query strings, we decode slashes.

      $params[] = $key . '=' . str_replace('%2F', '/', rawurlencode($value));

    }

  }

  return implode('&', $params);

}

/**

 * Prepares a 'destination' URL query parameter for use 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.

 *

 * @return

 *   An associative array containing the key:

 *   - destination: The path provided via the destination query string or, if

 *     not available, the current path.

 *

 * @see current_path()

 * @see drupal_goto()

 */

function drupal_get_destination() {

  $destination = &drupal_static(__FUNCTION__);

  if (isset($destination)) {