url

• Drupal 4.6
• Drupal 4.7
• Drupal 5
• Drupal 6
• Drupal 7

• View documentation
• List references

Definition

url($path = NULL, $options = array())
includes/common.inc, line 1256

Description

Generate a URL from a Drupal menu path. Will also pass-through existing URLs.

When creating links in modules, consider whether l() could be a better alternative than url().

Parameters

$path The Drupal path being linked to, such as "admin/content/node", or an existing URL like "http://drupal.org/". The special path '<front>' may also be given and will generate the site's base URL.

$options An associative array of additional options, with the following keys:

• 'query' A query string to append to the link, or an array of query key/value properties.
• 'fragment' A fragment identifier (or named anchor) to append to the link. Do not include the '#' character.
• 'absolute' (default FALSE) Whether to force the output to be an absolute link (beginning with http:). Useful for links that will be displayed outside the site, such as in an RSS feed.
• 'alias' (default FALSE) Whether the given path is an alias already.
• 'external' Whether the given path is an external URL.
• 'language' An optional language object. Used to build the URL to link to and look up the proper alias for the link.
• 'base_url' Only used internally, to modify the base URL when a language dependent URL requires so.
• 'prefix' Only used internally, to modify the path when a language dependent URL requires so.

Return value

A string containing a URL to the given path.

Code

<?php
function url($path = NULL, $options = array()) {
  // Merge in defaults.
  $options += array(
    'fragment' => '',
    'query' => '',
    'absolute' => FALSE,
    'alias' => FALSE,
    'prefix' => ''
  );
  if (!isset($options['external'])) {
    // Return an external link if $path contains an allowed absolute URL.
    // Only call the slow filter_xss_bad_protocol if $path contains a ':' before
    // any / ? or #.
    $colonpos = strpos($path, ':');
    $options['external'] = ($colonpos !== FALSE && !preg_match('![/?#]!', substr($path, 0, $colonpos)) && filter_xss_bad_protocol($path, FALSE) == check_plain($path));
  }

  // May need language dependent rewriting if language.inc is present.
  if (function_exists('language_url_rewrite')) {
    language_url_rewrite($path, $options);
  }
  if ($options['fragment']) {
    $options['fragment'] = '#'. $options['fragment'];
  }
  if (is_array($options['query'])) {
    $options['query'] = drupal_query_string_encode($options['query']);
  }

  if ($options['external']) {
    // Split off the fragment.
    if (strpos($path, '#') !== FALSE) {
      list($path, $old_fragment) = explode('#', $path, 2);
      if (isset($old_fragment) && !$options['fragment']) {
        $options['fragment'] = '#'. $old_fragment;
      }
    }
    // Append the query.
    if ($options['query']) {
      $path .= (strpos($path, '?') !== FALSE ? '&' : '?') . $options['query'];
    }
    // Reassemble.
    return $path . $options['fragment'];
  }

  global $base_url;
  static $script;
  static $clean_url;

  if (!isset($script)) {
    // On some web servers, such as IIS, we can't omit "index.php". So, we
    // generate "index.php?q=foo" instead of "?q=foo" on anything that is not
    // Apache.
    $script = (strpos($_SERVER['SERVER_SOFTWARE'], 'Apache') === FALSE) ? 'index.php' : '';
  }

  // Cache the clean_url variable to improve performance.
  if (!isset($clean_url)) {
    $clean_url = (bool)variable_get('clean_url', '0');
  }

  if (!isset($options['base_url'])) {
    // The base_url might be rewritten from the language rewrite in domain mode.
    $options['base_url'] = $base_url;
  }

  // Preserve the original path before aliasing.
  $original_path = $path;

  // The special path '<front>' links to the default front page.
  if ($path == '<front>') {
    $path = '';
  }
  elseif (!empty($path) && !$options['alias']) {
    $path = drupal_get_path_alias($path, isset($options['language']) ? $options['language']->language : '');
  }

  if (function_exists('custom_url_rewrite_outbound')) {
    // Modules may alter outbound links by reference.
    custom_url_rewrite_outbound($path, $options, $original_path);
  }

  $base = $options['absolute'] ? $options['base_url'] .'/' : base_path();
  $prefix = empty($path) ? rtrim($options['prefix'], '/') : $options['prefix'];
  $path = drupal_urlencode($prefix . $path);

  if ($clean_url) {
    // With Clean URLs.
    if ($options['query']) {
      return $base . $path .'?'. $options['query'] . $options['fragment'];
    }
    else {
      return $base . $path . $options['fragment'];
    }
  }
  else {
    // Without Clean URLs.
    $variables = array();
    if (!empty($path)) {
      $variables[] = 'q='. $path;
    }
    if (!empty($options['query'])) {
      $variables[] = $options['query'];
    }
    if ($query = join('&', $variables)) {
      return $base . $script .'?'. $query . $options['fragment'];
    }
    else {
      return $base . $options['fragment'];
    }
  }
}
?>