path.module 11.8 KB
Newer Older
Dries's avatar
Dries committed
1
<?php
Dries's avatar
Dries committed
2
// $Id$
Dries's avatar
Dries committed
3

Dries's avatar
 
Dries committed
4 5 6 7 8
/**
 * @file
 * Enables users to rename URLs.
 */

9 10 11 12 13
/**
 * Implementation of hook_help().
 */
function path_help($section) {
  switch ($section) {
Dries's avatar
 
Dries committed
14
    case 'admin/modules#description':
15
      return t('Allows users to rename URLs.');
16
    case 'admin/path':
17
      return t("<p>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.</p>");
18
    case 'admin/path/add':
19
      return t('<p>Enter the path you wish to create the alias for, followed by the name of the new alias.</p>');
20
    case 'admin/help#path':
Dries's avatar
Dries committed
21
      return t('
22 23 24 25
<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
Dries's avatar
Dries committed
26

27
image/tid/16 => store
Dries's avatar
Dries committed
28

Dries's avatar
 
Dries committed
29
taxonomy/term/7+19+20+21 => store/products/whirlygigs
Dries's avatar
Dries committed
30

Dries's avatar
 
Dries committed
31
node/3 => contact
32 33
</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>
Dries's avatar
 
Dries committed
34 35 36 37 38 39 40 41
<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>
Dries's avatar
Dries committed
42

43 44
<h3>Permissions</h3>
<p>Two permissions are related to URL aliasing: <em>create url aliases</em> and <em>administer url aliases</em>.</p>
Dries's avatar
 
Dries committed
45
<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. 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>
Dries's avatar
 
Dries committed
46

47
<h3>Mass URL aliasing</h3>
Dries's avatar
Dries committed
48
<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. You need to have a working PHP programming knowledge to make use of this feature however. Read on in the <a href="%mass-alias-doc">Drupal Handbook about mass url aliasing.</a></p>', array("%mass-alias-doc" => "http://drupal.org/node/23708"));
49 50
  }
}
Dries's avatar
 
Dries committed
51

52
/**
Dries's avatar
 
Dries committed
53
 * Implementation of hook_menu().
54
 */
Dries's avatar
 
Dries committed
55
function path_menu($may_cache) {
Dries's avatar
 
Dries committed
56
  $items = array();
Dries's avatar
 
Dries committed
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

  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);
Dries's avatar
 
Dries committed
72
    $items[] = array('path' => 'admin/path/add', 'title' => t('add alias'),
Dries's avatar
 
Dries committed
73 74 75 76 77
      'callback' => 'path_admin_edit',
      'access' => user_access('administer url aliases'),
      'type' => MENU_LOCAL_TASK);
  }

Dries's avatar
 
Dries committed
78
  return $items;
79
}
Dries's avatar
 
Dries committed
80

81 82 83 84
/**
 * Menu callback; presents an overview of all URL aliases.
 */
function path_admin() {
Dries's avatar
 
Dries committed
85
  return path_overview();
86 87 88 89 90 91
}

/**
 * Menu callback; handles pages for creating and editing URL aliases.
 */
function path_admin_edit($pid = 0) {
92
  if ($pid) {
Dries's avatar
 
Dries committed
93
    $alias = path_load($pid);
94
    drupal_set_title($alias['dst']);
Dries's avatar
 
Dries committed
95
    $output = path_form(path_load($pid));
Dries's avatar
Dries committed
96
  }
97
  else {
Dries's avatar
 
Dries committed
98
    $output = path_form();
99
  }
Dries's avatar
 
Dries committed
100

Dries's avatar
 
Dries committed
101
  return $output;
102
}
Dries's avatar
 
Dries committed
103

104 105 106 107
/**
 * Menu callback; handles deletion of an URL alias.
 */
function path_admin_delete($pid = 0) {
Dries's avatar
Dries committed
108
  db_query('DELETE FROM {url_alias} WHERE pid = %d', $pid);
Dries's avatar
 
Dries committed
109
  drupal_set_message(t('The alias has been deleted.'));
Dries's avatar
Dries committed
110
  drupal_goto('admin/path');
111 112 113 114 115
}

/**
 * Set an aliased path for a given Drupal path, preventing duplicates.
 */
Dries's avatar
 
Dries committed
116
function path_set_alias($path = NULL, $alias = NULL, $pid = NULL) {
Dries's avatar
 
Dries committed
117
  if ($path && !$alias) {
Dries's avatar
 
Dries committed
118
    db_query("DELETE FROM {url_alias} WHERE src = '%s'", $path);
119
    drupal_clear_path_cache();
Dries's avatar
 
Dries committed
120 121
  }
  else if (!$path && $alias) {
Dries's avatar
 
Dries committed
122
    db_query("DELETE FROM {url_alias} WHERE dst = '%s'", $alias);
123
    drupal_clear_path_cache();
Dries's avatar
 
Dries committed
124 125
  }
  else if ($path && $alias) {
Dries's avatar
 
Dries committed
126 127
    $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));
Dries's avatar
 
Dries committed
128 129 130

    // We have an insert:
    if ($path_count == 0 && $alias_count == 0) {
131
      db_query("INSERT INTO {url_alias} (src, dst) VALUES ('%s', '%s')", $path, $alias);
132
      drupal_clear_path_cache();
Dries's avatar
 
Dries committed
133
    }
Dries's avatar
 
Dries committed
134 135 136 137 138 139 140
    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);
      }
141
      drupal_clear_path_cache();
Dries's avatar
 
Dries committed
142 143
    }
    else if ($path_count == 0 && $alias_count == 1) {
Dries's avatar
 
Dries committed
144
      db_query("UPDATE {url_alias} SET src = '%s' WHERE dst = '%s'", $path, $alias);
145
      drupal_clear_path_cache();
Dries's avatar
 
Dries committed
146 147 148 149 150 151 152 153
    }
    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);
    }
  }
Dries's avatar
Dries committed
154 155
}

156 157 158 159
/**
 * Return a form for editing or creating an individual URL alias.
 */
function path_form($edit = '') {
Dries's avatar
Dries committed
160

161 162
  $form['src'] = array('#type' => 'textfield', '#title' => t('Existing system path'), '#default_value' => $edit['src'], '#size' => 60, '#maxlength' => 64, '#description' => t('Specify the existing path you wish to alias. For example: node/28, forum/1, taxonomy/term/1+2.'));
  $form['dst'] = array('#type' => 'textfield', '#default_value' => $edit['dst'], '#size' => 60, '#maxlength' => 64, '#description' => 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.'));
Dries's avatar
Dries committed
163

164
  if ($edit['pid']) {
165 166
    $form['pid'] = array('#type' => 'hidden', '#value' => $edit['pid']);
    $form['submit'] = array('#type' => 'submit', '#value' => t('Update alias'));
Dries's avatar
 
Dries committed
167 168
  }
  else {
169
    $form['submit'] = array('#type' => 'submit', '#value' => t('Create new alias'));
Dries's avatar
 
Dries committed
170 171
  }

172
  return drupal_get_form('path_form', $form);
Dries's avatar
Dries committed
173 174
}

Dries's avatar
 
Dries committed
175
/**
176 177 178 179
 * Implementation of hook_nodeapi().
 *
 * Allows URL aliases for nodes to be specified at node edit time rather
 * than through the administrative interface.
Dries's avatar
 
Dries committed
180
 */
Dries's avatar
 
Dries committed
181
function path_nodeapi(&$node, $op, $arg) {
182
  if (user_access('create url aliases') || user_access('administer url aliases')) {
Dries's avatar
 
Dries committed
183
    switch ($op) {
184
      case 'validate':
Dries's avatar
 
Dries committed
185 186 187
        $node->path = trim($node->path);
        if ($node->path && !valid_url($node->path)) {
          form_set_error('path', t('The path is invalid.'));
Dries's avatar
 
Dries committed
188
        }
Dries's avatar
 
Dries committed
189 190
        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.'));
Dries's avatar
 
Dries committed
191 192
        }
        break;
Dries's avatar
Dries committed
193

194
      case 'form':
195
        $form['path'] = array('#type' => 'fieldset', '#title' => t('URL path settings'), '#collapsible' => TRUE, '#collapsed' => TRUE);
196
        $form['path']['path'] = array('#type' => 'textfield', '#default_value' => $node->path, '#size' => 60, '#maxlength' => 250, '#collapsible' => TRUE, '#collapsed' => TRUE, '#description' => 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.'));
Dries's avatar
 
Dries committed
197
        if ($node->path) {
198
          $form['path']['pid'] = array('#type' => 'hidden', '#value' => db_result(db_query("SELECT pid FROM {url_alias} WHERE dst = '%s'", $node->path)));
Dries's avatar
 
Dries committed
199
        }
200
        return $form;
Dries's avatar
 
Dries committed
201

Dries's avatar
 
Dries committed
202 203 204 205 206 207 208 209
      case 'load':
        $path = "node/$node->nid";
        $alias = drupal_get_path_alias($path);
        if ($alias != $path) {
          $node->path = $alias;
        }
        break;

210 211 212
      case 'insert':
        // Don't try to insert if path is NULL.  We may have already set
        // the alias ahead of time.
Dries's avatar
 
Dries committed
213
        if ($node->path) {
Dries's avatar
 
Dries committed
214
          path_set_alias("node/$node->nid", $node->path);
Dries's avatar
 
Dries committed
215 216
        }
        break;
Dries's avatar
 
Dries committed
217

218
      case 'update':
Dries's avatar
 
Dries committed
219
        path_set_alias("node/$node->nid", $node->path, $node->pid);
Dries's avatar
 
Dries committed
220 221
        break;

222
      case 'delete':
Dries's avatar
 
Dries committed
223
        $path = "node/$node->nid";
224 225
        if (drupal_get_path_alias($path) != $path) {
          path_set_alias($path);
Dries's avatar
 
Dries committed
226 227 228
        }
        break;
    }
Dries's avatar
Dries committed
229 230 231
  }
}

232 233 234
/**
 * Implementation of hook_perm().
 */
Dries's avatar
Dries committed
235
function path_perm() {
236
  return array('create url aliases', 'administer url aliases');
Dries's avatar
Dries committed
237 238
}

239 240 241
/**
 * Return a listing of all defined URL aliases.
 */
Dries's avatar
Dries committed
242
function path_overview() {
243
  $sql = 'SELECT * FROM {url_alias}';
Dries's avatar
Dries committed
244
  $header = array(
Dries's avatar
 
Dries committed
245 246
    array('data' => t('Alias'), 'field' => 'dst', 'sort' => 'asc'),
    array('data' => t('System'), 'field' => 'src'),
Dries's avatar
 
Dries committed
247
    array('data' => t('Operations'), 'colspan' => '2')
Dries's avatar
Dries committed
248 249 250 251
  );
  $sql .= tablesort_sql($header);
  $result = pager_query($sql, 50);

252
  $destination = drupal_get_destination();
Dries's avatar
Dries committed
253
  while ($data = db_fetch_object($result)) {
254
    $rows[] = array($data->dst, $data->src, l(t('edit'), "admin/path/edit/$data->pid", array(), $destination), l(t('delete'), "admin/path/delete/$data->pid", array(), $destination));
Dries's avatar
Dries committed
255 256
  }

Dries's avatar
 
Dries committed
257
  if (!$rows) {
258
    $rows[] = array(array('data' => t('No URL aliases available.'), 'colspan' => '4'));
Dries's avatar
 
Dries committed
259 260
  }

261 262 263
  $output = theme('table', $header, $rows);
  $output .= theme('pager', NULL, 50, 0, tablesort_pager());
  return $output;
Dries's avatar
Dries committed
264 265
}

266 267 268
/**
 * Fetch a specific URL alias from the database.
 */
Dries's avatar
 
Dries committed
269
function path_load($pid) {
270
  return db_fetch_array(db_query('SELECT * FROM {url_alias} WHERE pid = %d', $pid));
Dries's avatar
 
Dries committed
271
}
Dries's avatar
Dries committed
272

273 274 275
/**
 * Verify that a new URL alias is valid, and save it to the database.
 */
276 277
function path_form_execute() {
  $edit = $GLOBALS['form_values'];
278 279 280
  $src = $edit['src'];
  $dst = $edit['dst'];
  $pid = $edit['pid'];
Dries's avatar
Dries committed
281

Dries's avatar
 
Dries committed
282
  if (!valid_url($src)) {
283
    form_set_error('src', t('The system path %path is invalid.', array('%path' => theme('placeholder', $src))));
Dries's avatar
Dries committed
284 285
  }

Dries's avatar
 
Dries committed
286
  if (!valid_url($dst)) {
287
    form_set_error('dst', t('The alias %alias is invalid.', array('%alias' => theme('placeholder', $dst))));
Dries's avatar
Dries committed
288 289
  }

290
  if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE pid != %d AND dst = '%s'", $pid, $dst))) {
291
    form_set_error('dst', t('The alias %alias is already in use.', array('%alias' => theme('placeholder', $dst))));
Dries's avatar
 
Dries committed
292
  }
Dries's avatar
Dries committed
293

Dries's avatar
 
Dries committed
294 295
  if (form_get_errors()) {
    return path_form($edit);
Dries's avatar
Dries committed
296
  }
Dries's avatar
 
Dries committed
297
  else {
Dries's avatar
 
Dries committed
298
    path_set_alias($src, $dst, $pid);
Dries's avatar
Dries committed
299

Dries's avatar
 
Dries committed
300
    drupal_set_message(t('The alias has been saved.'));
Dries's avatar
 
Dries committed
301
    drupal_goto('admin/path');
Dries's avatar
 
Dries committed
302
  }
Dries's avatar
Dries committed
303 304
}

305