path.module

<?php
/* $Id$ */

/**
 * @file
 * Enables users to rename URLs.
 */

/**
 * Implementation of hook_help().
 */
function path_help($section) {
  switch ($section) {
    case 'admin/modules#description':
      return t('Enables users to rename URLs.');
    case 'admin/path':
      return t("Drupal provides users complete control over URLs through aliasing.  This feature is typically used to make URLs human-readable or easy to remember.  For example, one could map the relative URL 'node/1' onto 'about'. Each system path can have multiple aliases.");
    case 'admin/path/add':
      return t('Enter the path you wish to create the alias for, followed by the name of the new alias.');
    case 'admin/help#path':
      return t("
<h3>Background</h3>
<p>A very powerful feature of Drupal is the ability to have control over all paths. The path module is the tool that provides this functionality and is part of the basic Drupal installation, although it is not enabled by default. Some examples of re-mapping paths are:</p>
<pre>
user/login => login

image/tid/16 => store

taxonomy/term/7+19+20+21 => store/products/whirlygigs

node/3 => contact
</pre>
<p>This functionality integrates seamlessly into node forms and also provides the administrator an interface to view all aliases that have been created.</p>
<p>Aliases have a many to one relationship with their original Drupal URLs. In other words you can have many different aliases map to a single path. An example of where a multiple aliases come in handy is creating a standard RSS feed URL:</p>

<pre>
node/feed => rss.xml
node/feed => index.rdf
</pre>

<p>When Drupal generates links for a path with multiple aliases it will choose the first alias created per system URL.  So in our above example, Drupal would use rss.xml as the default alias rather than index.rdf. To change this behavior, delete the aliases for node/feed and create the index.rdf alias before rss.xml.</p>

<h3>Permissions</h3>
<p>Two permissions are related to URL aliasing: <em>create url aliases</em> and <em>administer url aliases</em>.</p>
<ol><li><strong>create url aliases</strong> - Allows users to create aliases for nodes. Enabling this permission will display a path field to the user in any node form, allowing them to enter an alias for that node. They will be able to edit/delete the alias after it is created using the same form.</li><li><strong>administer url aliases</strong> - Allows users to access the alias administration interface. They must also have the <em>access administration pages</em> permission set as well. This interface displays all aliases and provides a way to create and modify them. This is also the location to build aliases for things other than nodes. For example, you can create an alias for a taxonomy URL or even re-map the admin path (although the original admin path will still be accessible since aliases do not cancel out original paths).</li></ol>

<h3>Mass URL aliasing</h3>
<p>Drupal also comes with user defined mass URL aliasing capabilities. You might like to see completely different URLs used by Drupal, or even URLs translated to the visitors' native language, in which case this feature is handy. Only an administrator with access to the website source code can set up this kind of aliases. You can define a <code>conf_url_rewrite</code> function in conf.php, following this example:</p>
<pre>
function conf_url_rewrite(\$path, \$mode = 'incoming') {
  if (\$mode == 'incoming') { // URL coming from a client
    return preg_replace('!^display/(\\d+)\$!', 'node/\\1', \$path);
  }
  else { // URL going out to a client
    \$aliased = preg_replace('!^node/(\\d+)\$!', 'display/\\1', \$path);
    if (\$aliased != \$path) { return \$aliased; }
  }
}
</pre>
<p>This function will shorten every <code>node/\$node_id</code> type of URL to <code>display/\$node_id</code>. Individual URL aliases defined on the browser interface of Drupal take precedence, so if you have the 'contact' page alias from the example above, then the <code>display/3</code> alias will not be effective when outgoing links are created. Incoming URLs however always work with the mass URL aliased variant. Only the 'incoming' and 'outgoing' modes are supposed to be supported by your <code>conf_url_rewrite</code> function.</p>
<p>You cannot only use this feature to shorten the URLs, or to translate them to you own language, but also to add completely new subURLs to an already existing module's URL space, or to compose a bunch of existing stuff together to a common URL space. You can create a <code>news</code> section for example aliasing nodes and taxonomy overview pages falling under a 'news' vocabulary, thus having <code>news/15</code> and <code>news/sections/3</code> instead of <code>node/15</code> and <code>taxonomy/term/3</code>. You need extensive knowledge of Drupal's inner workings and regular expressions though to make such advanced aliases.</p>");
  }
}

/**
 * Implementation of hook_menu().
 */
function path_menu($may_cache) {
  $items = array();

  if ($may_cache) {
    $items[] = array('path' => 'admin/path', 'title' => t('url aliases'),
      'callback' => 'path_admin',
      'access' => user_access('administer url aliases'));
    $items[] = array('path' => 'admin/path/edit', 'title' => t('edit alias'),
      'callback' => 'path_admin_edit',
      'access' => user_access('administer url aliases'),
      'type' => MENU_CALLBACK);
    $items[] = array('path' => 'admin/path/delete', 'title' => t('delete alias'),
      'callback' => 'path_admin_delete',
      'access' => user_access('administer url aliases'),
      'type' => MENU_CALLBACK);
    $items[] = array('path' => 'admin/path/list', 'title' => t('list'),
      'type' => MENU_DEFAULT_LOCAL_TASK, 'weight' => -10);
    $items[] = array('path' => 'admin/path/add', 'title' => t('add'),
      'callback' => 'path_admin_edit',
      'access' => user_access('administer url aliases'),
      'type' => MENU_LOCAL_TASK);
  }

  return $items;
}

/**
 * Menu callback; presents an overview of all URL aliases.
 */
function path_admin() {
  print theme('page', path_overview());
}

/**
 * Menu callback; handles pages for creating and editing URL aliases.
 */
function path_admin_edit($pid = 0) {
  if ($_POST['op'] == t('Create new alias') || $_POST['op'] == t('Update alias')) {
    $output = path_save($_POST['edit']);
  }
  elseif ($pid) {
    $alias = path_load($pid);
    $title = $alias['dst'];
    $output = path_form(path_load($pid));
  }
  else {
    $output = path_form();
  }

  print theme('page', $output, $title);
}

/**
 * Menu callback; handles deletion of an URL alias.
 */
function path_admin_delete($pid = 0) {
  db_query('DELETE FROM {url_alias} WHERE pid = %d', $pid);
  drupal_set_message(t('The alias has been deleted.'));
  drupal_goto('admin/path');
}

/**
 * Set an aliased path for a given Drupal path, preventing duplicates.
 */
function path_set_alias($path = NULL, $alias = NULL, $pid = NULL) {
  if ($path && !$alias) {
    db_query("DELETE FROM {url_alias} WHERE src = '%s'", $path);
    drupal_rebuild_path_map();
  }
  else if (!$path && $alias) {
    db_query("DELETE FROM {url_alias} WHERE dst = '%s'", $alias);
    drupal_rebuild_path_map();
  }
  else if ($path && $alias) {
    $path_count = db_result(db_query("SELECT COUNT(src) FROM {url_alias} WHERE src = '%s'", $path));
    $alias_count = db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE dst = '%s'", $alias));

    // We have an insert:
    if ($path_count == 0 && $alias_count == 0) {
      db_query("INSERT INTO {url_alias} (src, dst) VALUES ('%s', '%s')", $path, $alias);
      drupal_rebuild_path_map();
    }
    else if ($path_count >= 1 && $alias_count == 0) {
      if ($pid) {
        db_query("UPDATE {url_alias} SET dst = '%s', src = '%s' WHERE pid = %d", $alias, $path, $pid);
      }
      else {
        db_query("INSERT INTO {url_alias} (src, dst) VALUES ('%s', '%s')", $path, $alias);
      }
      drupal_rebuild_path_map();
    }
    else if ($path_count == 0 && $alias_count == 1) {
      db_query("UPDATE {url_alias} SET src = '%s' WHERE dst = '%s'", $path, $alias);
      drupal_rebuild_path_map();
    }
    else if ($path_count == 1 && $alias_count == 1) {
      // This will delete the path that alias was originally pointing to:
      path_set_alias(NULL, $alias);
      path_set_alias($path);
      path_set_alias($path, $alias);
    }
  }
}

/**
 * Return a form for editing or creating an individual URL alias.
 */
function path_form($edit = '') {

  $form .= form_textfield(t('Existing system path'), 'src', $edit['src'], 50, 64, t('Specify the existing path you wish to alias. For example: node/28, forum/1, taxonomy/term/1+2.'));
  $form .= form_textfield(t('New path alias'), 'dst', $edit['dst'], 50, 64, t('Specify an alternative path by which this data can be accessed.  For example, type "about" when writing an about page.  Use a relative path and don\'t add a trailing slash or the URL alias won\'t work.'));

  if ($edit['pid']) {
    $form .= form_hidden('pid', $edit['pid']);
    $form .= form_submit(t('Update alias'));
  }
  else {
    $form .= form_submit(t('Create new alias'));
  }

  return form($form);
}

/**
 * Implementation of hook_nodeapi().
 *
 * Allows URL aliases for nodes to be specified at node edit time rather
 * than through the administrative interface.
 */
function path_nodeapi(&$node, $op, $arg) {
  if (user_access('create url aliases') || user_access('administer url aliases')) {

    switch ($op) {
      case 'validate':
        // is_null provides a mechanism for us to determine if this is the first
        // viewing of the form.  If it is the first time, load the alias, if it isn't
        // (i.e., user has clicked preview) let them work with their current form alias.
        if (is_null($node->path)) {
          $path = "node/$node->nid";
          $alias = drupal_get_path_alias($path);
          if ($alias != $path) {
            $node->path = $alias;
          }
        }
        else {
          $node->path = trim($node->path);
          if ($node->path && !valid_url($node->path)) {
            form_set_error('path', t('The path is invalid.'));
          }
          else if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE dst = '%s' AND src != '%s'", $node->path, "node/$node->nid"))) {
            form_set_error('path', t('The path is already in use.'));
          }
        }
        break;

      case 'form pre':
        $output = form_textfield(t('Path alias'), 'path', $node->path, 60, 250, t('Optionally specify an alternative URL by which this node can be accessed.  For example, type "about" when writing an about page.  Use a relative path and don\'t add a trailing slash or the URL alias won\'t work.'));
        if ($node->path) {
          $output .= form_hidden('pid', db_result(db_query("SELECT pid FROM {url_alias} WHERE dst = '%s'", $node->path)));
        }
        return $output;

      case 'insert':
        // Don't try to insert if path is NULL.  We may have already set
        // the alias ahead of time.
        if ($node->path) {
          path_set_alias("node/$node->nid", $node->path);
        }
        break;
      case 'update':
        path_set_alias("node/$node->nid", $node->path, $node->pid);
        break;

      case 'delete':
        $path = "node/$node->nid";
        if (drupal_get_path_alias($path) != $path) {
          path_set_alias($path);
        }
        break;
    }
  }
}

/**
 * Implementation of hook_perm().
 */
function path_perm() {
  return array('create url aliases', 'administer url aliases');
}

/**
 * Return a listing of all defined URL aliases.
 */
function path_overview() {
  $sql = 'SELECT * FROM {url_alias}';
  $header = array(
    array('data' => t('Alias'), 'field' => 'dst', 'sort' => 'asc'),
    array('data' => t('System'), 'field' => 'src'),
    array('data' => t('Operations'), 'colspan' => 2)
  );
  $sql .= tablesort_sql($header);
  $result = pager_query($sql, 50);

  while ($data = db_fetch_object($result)) {
    $rows[] = array($data->dst, $data->src, l(t('edit'), "admin/path/edit/$data->pid"), l(t('delete'), "admin/path/delete/$data->pid"));
  }

  if ($pager = theme('pager', NULL, 50, 0, tablesort_pager())) {
    $rows[] = array(array('data' => $pager, 'colspan' => '4'));
  }

  if (!$rows) {
    $rows[] = array(array('data' => t('No URL aliases available.'), 'colspan' => '4'));
  }

  return theme('table', $header, $rows);
}

/**
 * Fetch a specific URL alias from the database.
 */
function path_load($pid) {
  return db_fetch_array(db_query('SELECT * FROM {url_alias} WHERE pid = %d', $pid));
}

/**
 * Verify that a new URL alias is valid, and save it to the database.
 */
function path_save($edit) {
  $src = $edit['src'];
  $dst = $edit['dst'];
  $pid = $edit['pid'];

  if (!valid_url($src)) {
    form_set_error('src', t('The system path %path is invalid.', array('%path' => "<em>$src</em>")));
  }

  if (!valid_url($dst)) {
    form_set_error('dst', t('The alias %alias is invalid.', array('%alias' => "<em>$dst</em>")));
  }

  if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE pid != %d AND dst = '%s'", $pid, $dst))) {
    form_set_error('dst', t('The alias %alias is already in use.', array('%alias' => "<em>$dst</em>")));
  }

  if (form_get_errors()) {
    return path_form($edit);
  }
  else {
    path_set_alias($src, $dst, $pid);

    drupal_set_message(t('The alias has been saved.'));
    drupal_goto('admin/path');
  }
}

?>