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

4 5 6 7 8
/**
 * Implementation of hook_help().
 */
function path_help($section) {
  switch ($section) {
Dries's avatar
 
Dries committed
9
    case 'admin/modules#description':
Dries's avatar
 
Dries committed
10
      return t('Enables users to rename URLs.');
11
    case 'admin/path':
Dries's avatar
 
Dries committed
12
      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'.");
13 14 15 16 17 18 19 20
    case 'admin/path/add':
      return t('Enter the path you wish to create the alias for, followed by the name of the new alias. Each path can be associated with only one 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
Dries's avatar
Dries committed
21

22
image/tid/16 => store
Dries's avatar
Dries committed
23

24
taxonomy/page/or/7,19,20,21 => store/products/whirlygigs
Dries's avatar
Dries committed
25

Dries's avatar
 
Dries committed
26
node/3 => contact
27 28 29
</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 1 to 1 relationship with their original Drupal URLs. In other words you cannot have an alias map to more than one path. Likewise, a Drupal URL can't be mapped to more than one alias.</p>
Dries's avatar
Dries committed
30

31 32 33
<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>
Dries's avatar
 
Dries committed
34

35 36 37 38 39
<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
Dries's avatar
 
Dries committed
40
    return preg_replace('!^display/(\\d+)\$!', 'node/\\1', \$path);
41 42
  }
  else { // URL going out to a client
Dries's avatar
 
Dries committed
43
    \$aliased = preg_replace('!^node/(\\d+)\$!', 'display/\\1', \$path);
44 45 46 47
    if (\$aliased != \$path) { return \$aliased; }
  }
}
</pre>
Dries's avatar
 
Dries committed
48 49
<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/view/or/3</code>. You need extensive knowledge of Drupal's inner workings and regular expressions though to make such advanced aliases.</p>");
50 51
  }
}
Dries's avatar
 
Dries committed
52

53
/**
Dries's avatar
 
Dries committed
54
 * Implementation of hook_menu().
55
 */
Dries's avatar
 
Dries committed
56 57
function path_menu() {
  $items = array();
Dries's avatar
 
Dries committed
58
  $items[] = array('path' => 'admin/path', 'title' => t('url aliases'),
Dries's avatar
 
Dries committed
59 60 61 62 63 64 65 66 67 68
    '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);
Dries's avatar
 
Dries committed
69 70 71
  $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'),
Dries's avatar
 
Dries committed
72 73 74 75
    'callback' => 'path_admin_edit',
    'access' => user_access('administer url aliases'),
    'type' => MENU_LOCAL_TASK);
  return $items;
76
}
Dries's avatar
 
Dries committed
77

78 79 80 81 82 83 84 85 86 87 88 89
/**
 * 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')) {
Dries's avatar
 
Dries committed
90
    path_save($_POST['edit']);
Dries's avatar
Dries committed
91
  }
92 93 94 95 96 97 98
  else {
    if ($pid) {
      $output = path_form(path_load($pid));
    }
    else {
      $output = path_form();
    }
Dries's avatar
 
Dries committed
99 100

    print theme('page', $output);
101 102
  }
}
Dries's avatar
 
Dries committed
103

104 105 106 107 108 109
/**
 * Menu callback; handles deletion of an URL alias.
 */
function path_admin_delete($pid = 0) {
  path_delete($pid);
  print theme('page', path_overview());
Dries's avatar
Dries committed
110 111
}

112 113 114 115 116 117 118 119 120 121
/**
 * Menu callback; presents the path-specific information from admin/help.
 */
function path_admin_help() {
  print theme('page', path_help('admin/help#path'));
}

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

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

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

Dries's avatar
 
Dries committed
162
  $form .= form_textfield(t('Existing path'), 'src', $edit['src'], 50, 64, t('Specify the existing path you wish to alias. For example: node/28, forum/1, taxonomy/page/or/1,2.'));
163
  $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.'));
Dries's avatar
Dries committed
164

165 166 167
  if ($edit['pid']) {
    $form .= form_hidden('pid', $edit['pid']);
    $form .= form_submit(t('Update alias'));
Dries's avatar
 
Dries committed
168 169
  }
  else {
170
    $form .= form_submit(t('Create new alias'));
Dries's avatar
 
Dries committed
171 172 173
  }

  return form($form);
Dries's avatar
Dries committed
174 175
}

Dries's avatar
 
Dries committed
176
/**
177 178 179 180
 * 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
181
 */
Dries's avatar
 
Dries committed
182
function path_nodeapi(&$node, $op, $arg) {
183
  if (user_access('create url aliases') || user_access('administer url aliases')) {
Dries's avatar
Dries committed
184

Dries's avatar
 
Dries committed
185
    switch ($op) {
186
      case 'validate':
Dries's avatar
 
Dries committed
187 188 189
        // 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.
190
        if (is_null($node->path)) {
Dries's avatar
 
Dries committed
191
          $path = "node/$node->nid";
192 193 194 195
          $alias = drupal_get_path_alias($path);
          if ($alias != $path) {
            $node->path = $alias;
          }
Dries's avatar
 
Dries committed
196 197
        }
        else {
198 199
          $node->path = trim($node->path);
          if ($node->path && !valid_url($node->path)) {
Dries's avatar
 
Dries committed
200
            form_set_error('path', t('The path is invalid.'));
Dries's avatar
 
Dries committed
201
          }
Dries's avatar
 
Dries committed
202
          else if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE dst = '%s' AND src != '%s'", $node->path, "node/$node->nid"))) {
Dries's avatar
 
Dries committed
203
            form_set_error('path', t('The path is already in use.'));
Dries's avatar
 
Dries committed
204 205 206
          }
        }
        break;
Dries's avatar
Dries committed
207

208
      case 'form pre':
Dries's avatar
 
Dries committed
209
        return 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.'));
Dries's avatar
 
Dries committed
210

211 212 213
      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
214
        if ($node->path) {
Dries's avatar
 
Dries committed
215
          path_set_alias("node/$node->nid", $node->path);
Dries's avatar
 
Dries committed
216 217
        }
        break;
218
      case 'update':
Dries's avatar
 
Dries committed
219
        path_set_alias("node/$node->nid", $node->path);
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(
245 246 247
    array('data' => t('alias'), 'field' => 'dst', 'sort' => 'asc'),
    array('data' => t('normal'), 'field' => 'src'),
    array('data' => t('operations'), 'colspan' => 2)
Dries's avatar
Dries committed
248 249 250 251 252
  );
  $sql .= tablesort_sql($header);
  $result = pager_query($sql, 50);

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

256 257
  if ($pager = theme('pager', NULL, 50, 0, tablesort_pager())) {
    $rows[] = array(array('data' => $pager, 'colspan' => '4'));
Dries's avatar
Dries committed
258 259
  }

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

264
  return theme('table', $header, $rows);
Dries's avatar
Dries committed
265 266
}

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

274 275 276
/**
 * Remove an URL alias from the database.
 */
Dries's avatar
 
Dries committed
277
function path_delete($pid) {
278 279
  db_query('DELETE FROM {url_alias} WHERE pid = %d', $pid);
  drupal_set_message(t('the alias has been deleted.'));
Dries's avatar
 
Dries committed
280
}
Dries's avatar
Dries committed
281

282 283 284
/**
 * Verify that a new URL alias is valid, and save it to the database.
 */
Dries's avatar
 
Dries committed
285
function path_save($edit) {
286 287 288
  $src = $edit['src'];
  $dst = $edit['dst'];
  $pid = $edit['pid'];
Dries's avatar
Dries committed
289

Dries's avatar
 
Dries committed
290
  if (!valid_url($src)) {
Dries's avatar
 
Dries committed
291
    form_set_error('src', t('the normal path "%src" is invalid.', array('%src' => $src)));
Dries's avatar
Dries committed
292 293
  }

294
  if (db_result(db_query("SELECT COUNT(src) FROM {url_alias} WHERE pid != %d AND src = '%s'", $pid, $src))) {
Dries's avatar
 
Dries committed
295
    form_set_error('src', t('the normal path "%src" is already aliased.', array('%src' => $src)));
Dries's avatar
Dries committed
296 297
  }

Dries's avatar
 
Dries committed
298
  if (!valid_url($dst)) {
Dries's avatar
 
Dries committed
299
    form_set_error('dst', t('the alias "%dst" is invalid.', array('%dst' => $dst)));
Dries's avatar
Dries committed
300 301
  }

302
  if (db_result(db_query("SELECT COUNT(dst) FROM {url_alias} WHERE pid != %d AND dst = '%s'", $pid, $dst))) {
Dries's avatar
 
Dries committed
303
    form_set_error('dst', t('the alias "%dst" is already in use.', array('%dst' => $dst)));
Dries's avatar
 
Dries committed
304
  }
Dries's avatar
Dries committed
305

Dries's avatar
 
Dries committed
306 307
  if (form_get_errors()) {
    return path_form($edit);
Dries's avatar
Dries committed
308
  }
Dries's avatar
 
Dries committed
309
  else {
310 311 312
    // Normally, you would use path_set_alias() to update the paths table,
    // but this is a special case.  We want to modify a specific row and the only
    // way to do that is with pid.
Dries's avatar
 
Dries committed
313 314

    if ($pid) {
315
      db_query("UPDATE {url_alias} SET src = '%s', dst = '%s' WHERE pid = %d", $src, $dst, $pid);
Dries's avatar
 
Dries committed
316 317 318 319
    }
    else {
      path_set_alias($src, $dst);
    }
Dries's avatar
Dries committed
320

Dries's avatar
 
Dries committed
321
    drupal_set_message(t('the alias has been saved.'));
Dries's avatar
 
Dries committed
322
    drupal_goto('admin/path');
Dries's avatar
 
Dries committed
323
  }
Dries's avatar
Dries committed
324 325 326
}

?>