function hook_url_outbound_alter

You are here

7 system.api.php hook_url_outbound_alter(&$path, &$options, $original_path)

Alters outbound URLs.


$path: The outbound path to alter, not adjusted for path aliases yet. It won't be adjusted for path aliases until all modules are finished altering it, thus being consistent with hook_url_inbound_alter(), which adjusts for all path aliases before allowing modules to alter it. This may have been altered by other modules before this one.

$options: A set of URL options for the URL so elements such as a fragment or a query string can be added to the URL.

$original_path: The original path, before being altered by any modules.

See also


Related topics

2 functions implement hook_url_outbound_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

locale_url_outbound_alter in modules/locale/locale.module
Implements hook_url_outbound_alter().
url_alter_test_url_outbound_alter in modules/simpletest/tests/url_alter_test.module
Implements hook_url_outbound_alter().
1 invocation of hook_url_outbound_alter()
url in includes/
Generates an internal or external URL.


modules/system/system.api.php, line 4248
Hooks provided by Drupal core and the System module.


function hook_url_outbound_alter(&$path, &$options, $original_path) {
  // Use an external RSS feed rather than the Drupal one.
  if ($path == 'rss.xml') {
    $path = '';
    $options['external'] = TRUE;

  // Instead of pointing to user/[uid]/edit, point to user/me/edit.
  if (preg_match('|^user/([0-9]*)/edit(/.*)?|', $path, $matches)) {
    global $user;
    if ($user->uid == $matches[1]) {
      $path = 'user/me/edit' . $matches[2];


This replaces custom_url_rewrite_outbound() from Drupal 6.

If you want to override an existing url_alias:

- change your $path as you need
- set $options['alias'] = $path;

This prevents url() in from running a drupal_lookup_path(), effectively changing the url_alias (temporarily, the url_alias is not changed).

This example makes it so that login and logout links everywhere on the site (that run through url() of course) always take the user back to the page that they clicked login or logout.

* Implements hook_url_outbound_alter().
function mymodule_url_outbound_alter(&$path, &$options, $original_path) {
// Always make login/logout links go to the current page.
switch ($path) {
$options['query']['destination'] = $_GET['q'];

its unfortunate that, although this seems to imply that $options can be altered; this is not actually the case for most $options.

Only those handled by url() such as fragment and query may be altered. Since the l() function does not get the altered $options returned to it from the url() function you can't alter such $options as title or attributes (which is really annoying that these can't be altered, afaikt).

There is a handy Drupal 6 contrib module that provides this hook:

Note that when changing $path, if this hook is being invoked from url() it will still attempt to do a lookup using drupal_get_path_alias() for $original_path which could overwrite your change. To prevent this call, also set $options['alias'] = TRUE which will skip the drupal_get_path_alias() call.