URL alias

In Drupal, a URL alias is a stored mapping from a readable path to an internal system path. When a request arrives, Drupal looks up the system path behind the alias, and it writes the alias into the links it generates, so visitors see only the readable form. Editors set aliases through the core Path module.

How aliases work in Drupal 11

Drupal stores each alias as a path_alias entity, defined by the core Path Alias module, with two required fields: path, labeled "System path", and alias, labeled "URL alias". A language code is stored with it. Both values must begin with a slash. On save, Drupal trims whitespace and trailing slashes from the alias.

The mapping runs in both directions through AliasPathProcessor. For an incoming request, processInbound() asks the alias manager for the system path behind the alias. When Drupal builds a link, processOutbound() asks for the alias that belongs to the system path. The two lookups are AliasManagerInterface::getPathByAlias() and getAliasByPath(). When nothing matches, each returns the value it was given.

Aliases are validated on save. An alias that another path already uses in the same language is refused, and a clash that differs only in capitalization is reported separately.

Example

To give a content item an alias, open its edit form, type /about-us in the URL alias field and save. You need the "Create and edit URL aliases" permission, plus permission to edit the item.

To review or change aliases site-wide, go to Configuration › Search and metadata › URL aliases. The page lists every alias, and each row has an Edit action. Editing there needs the "Administer URL aliases" permission.

Common mistakes

• Forgetting the leading slash. Core validation requires it.
• Treating an alias as a redirect. An alias does not forward anyone. If you change the alias of a published page, the old address needs a redirect. The Redirect module has a setting to create redirects automatically when aliases change.
• Reusing an alias. Two paths cannot share one alias in the same language.

For marketing and content teams

The alias is the part of the address people read, share and bookmark. The Path module help says aliases make URLs more readable and help search engines index content. Agree on the wording with your developers before launch, and treat changes to live pages as a task that needs a redirect. Typing every alias by hand is slow, so you can let Pathauto generate them from patterns.

With DXPR

The DXPR CMS project page lists Pathauto as the source of its clean, SEO-friendly URLs. Read more about DXPR CMS.

Sources

• Drupal User Guide: Concept: Paths, aliases, and URLs
• Drupal core 11.2.0: Path module help text
• Drupal core 11.2.0: Help topic Editing a URL alias
• Drupal core 11.2.0: Help topic Creating a URL alias for a content item
• PathAlias entity class, Drupal API
• AliasManagerInterface, Drupal API
• Drupal core 11.2.0: AliasPathProcessor
• Drupal core 11.2.0: UniquePathAliasConstraint
• Drupal.org: Redirect project
• Drupal.org: DXPR CMS project