By plach on
Change record status: 
Published (View all published change records)
Project: 
Drupal core
Introduced in branch: 
8.8.x
Introduced in version: 
8.8.0
Issue links: 
https://www.drupal.org/node/3084983
https://www.drupal.org/node/3092090
https://www.drupal.org/node/3093747
Description: 

The Path Alias management API has always been part of the core path subsystem. After path alias were converted to entities, the API is now provided by the new path_alias module. This module is required in Drupal 8.8.0 and following and is planned to be made optional in Drupal 9.0.0.

To achieve this, several core services were deprecated or aliased. Specifically:

Legacy service New service Status Notes
path.alias_manager path_alias.manager Deprecated The legacy service is still available and shares its internal state with the new one to keep performance optimizations working.
path.alias_whitelist path_alias.whitelist Aliased The legacy service no longer exists, the old name is still available as a service alias. Service providers wishing to support also 8.7.x will need to use ContainerBuilder::findDefinition('path.alias_whitelist').
path_subscriber path_alias.subscriber Deprecated The service has been deprecated and is no longer registering itself as an event subscriber but still exists for backwards compatibility.
path_processor_alias path_alias.path_processor Deprecated The service has been deprecated and is no longer registering itself as a path processor but still exists for backwards compatibility.

Note: in general, event subscriber and similar services are considered internal and should not be relied upon by other code.

The following interfaces and classes were deprecated accordingly:

Legacy interface/class New interface/class
Drupal\Core\Path\AliasManagerInterface Drupal\path_alias\AliasManagerInterface
Drupal\Core\Path\AliasManager Drupal\path_alias\AliasManager
Drupal\Core\Path\AliasWhitelistInterface Drupal\path_alias\AliasWhitelistInterface
Drupal\Core\Path\AliasWhitelist Drupal\path_alias\AliasWhitelist
Drupal\Core\EventSubscriber\PathSubscriber Drupal\path_alias\EventSubscriber\PathAliasSubscriber
Drupal\Core\PathProcessor\PathProcessorAlias Drupal\path_alias\PathProcessor\AliasPathProcessor

Updates required

To make code D8.8-compatible the following changes are required:

  • Service providers altering or decorating the legacy path.alias_manager service need to do the same also with the new path_alias.manager service.
  • Service providers altering or decorating the legacy path.alias_whitelist service need to either switch to the new path_alias.whitelist service name or to use ContainerBuilder::findDefinition('path.alias_whitelist') to retrieve the service definition.

To make code D9-compatible the following changes are required:

  • API consumers, service providers, or service decorators need to replace the legacy service names with the new ones in all references.
  • Classes implementing the legacy interfaces need to replace them with the new ones in their implements clause.
  • Interfaces or classes extending the legacy ones need to replace them with the new ones in their extends clause.

Most importantly, as mentioned above, the path_alias module will be optional in Drupal 9, so code should be refactored not to assume the availability of the Path Alias API or should add an explicit dependency on the path_alias module.

Impacts: 
Module developers

Comments

hughworm’s picture

hughworm commented

Given a path like /node/123, to get an aliased URL is this the right way?

    $path = '/node/123';
    $alias_manager = \Drupal::service('path_alias.manager');
    $alias = $alias_manager->getAliasByPath($path);
    $url = Url::fromUri('base:'.$alias);

If at first you don’t succeed, call it version 1.0.

mlncn’s picture

mlncn commented

In particular, it seems to me that in many cases you just have to make your module incompatible with older versions of Drupal, and update your .info.yml file to have this:

core_version_requirement: ^8.8 || ^9

dependencies:
  - drupal:path_alias

benjamin, Agaric