url
- Versions
- 4.6 – 5
url($path = NULL,$query= NULL,$fragment= NULL,$absolute= FALSE)- 6
url($path = NULL, $options = array())- 7
url($path = NULL, array $options = array())
Generate a URL.
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", 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': An array of query key/value-pairs (without any URL-encoding) to append to the link.
- 'fragment': A fragment identifier (or named anchor) to append to the link. Do not include the leading '#' character.
- 'absolute': Defaults to 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 a RSS feed.
- 'alias': Defaults to FALSE. Whether the given path is a URL 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.
- 'https': Whether this URL should point to a secure location. If not defined, the current scheme is used, so the user stays on http or https respectively. TRUE enforces HTTPS and FALSE enforces HTTP, but HTTPS can only be enforced when the variable 'https' is set to TRUE.
- '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
includes/common.inc, line 2453
<?php
function url($path = NULL, array $options = array()) {
static $url_outbound;
// Merge in defaults.
$options += array(
'fragment' => '',
'query' => array(),
'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 #.
// Note: we could use url_is_external($path) here, but that would
// requre another function call, and performance inside url() is critical.
$colonpos = strpos($path, ':');
$options['external'] = ($colonpos !== FALSE && !preg_match('![/?#]!', substr($path, 0, $colonpos)) && filter_xss_bad_protocol($path, FALSE) == check_plain($path));
}
// Preserve the original path before altering or aliasing.
$original_path = $path;
// Allow other modules to alter the outbound URL and options.
// Since PHP code cannot be unloaded, we statically cache the implementations
// of hook_url_outbound_alter() and only invoke them in case there are any.
if (!isset($url_outbound)) {
$url_outbound = (bool) module_implements('url_outbound_alter');
}
if ($url_outbound) {
drupal_alter('url_outbound', $path, $options, $original_path);
}
if ($options['fragment']) {
$options['fragment'] = '#' . $options['fragment'];
}
if ($options['external']) {
// Split off the fragment.
if (strpos($path, '#') !== FALSE) {
list($path, $old_fragment) = explode('#', $path, 2);
// If $options contains no fragment, take it over from the path.
if (isset($old_fragment) && !$options['fragment']) {
$options['fragment'] = '#' . $old_fragment;
}
}
// Append the query.
if ($options['query']) {
$path .= (strpos($path, '?') !== FALSE ? '&' : '?') . drupal_http_build_query($options['query']);
}
if (isset($options['https']) && variable_get('https', FALSE)) {
if ($options['https'] === TRUE) {
$path = str_replace('http://', 'https://', $path);
}
elseif ($options['https'] === FALSE) {
$path = str_replace('https://', 'http://', $path);
}
}
// Reassemble.
return $path . $options['fragment'];
}
global $base_url, $base_secure_url, $base_insecure_url;
// Use the advanced drupal_static() pattern, since this is called very often.
static $drupal_static = array();
isset($drupal_static[__FUNCTION__]) || ($drupal_static[__FUNCTION__] = &drupal_static(__FUNCTION__));
$script = &$drupal_static[__FUNCTION__];
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' : '';
}
// The base_url might be rewritten from the language rewrite in domain mode.
if (!isset($options['base_url'])) {
if (isset($options['https']) && variable_get('https', FALSE)) {
if ($options['https'] === TRUE) {
$options['base_url'] = $base_secure_url;
$options['absolute'] = TRUE;
}
elseif ($options['https'] === FALSE) {
$options['base_url'] = $base_insecure_url;
$options['absolute'] = TRUE;
}
}
else {
$options['base_url'] = $base_url;
}
}
// The special path '<front>' links to the default front page.
if ($path == '<front>') {
$path = '';
}
elseif (!empty($path) && !$options['alias']) {
$language = isset($options['language']) && isset($options['language']->language) ? $options['language']->language : '';
$alias = drupal_get_path_alias($original_path, $language);
if ($alias != $original_path) {
$path = $alias;
}
}
$base = $options['absolute'] ? $options['base_url'] . '/' : base_path();
$prefix = empty($path) ? rtrim($options['prefix'], '/') : $options['prefix'];
// With Clean URLs.
if (!empty($GLOBALS['conf']['clean_url'])) {
$path = drupal_encode_path($prefix . $path);
if ($options['query']) {
return $base . $path . '?' . drupal_http_build_query($options['query']) . $options['fragment'];
}
else {
return $base . $path . $options['fragment'];
}
}
// Without Clean URLs.
else {
$path = $prefix . $path;
$query = array();
if (!empty($path)) {
$query['q'] = $path;
}
if ($options['query']) {
// We do not use array_merge() here to prevent overriding $path via query
// parameters.
$query += $options['query'];
}
if ($query) {
return $base . $script . '?' . drupal_http_build_query($query) . $options['fragment'];
}
else {
return $base . $options['fragment'];
}
}
}
?>