class PathChangedHelper

Provides helper functions for handling path changes.

When a route's path changes, we temporarily add a route to handle the old path and redirect to the new one. This temporary route is for backwards compatibility (BC). If the original route is example.route, then the BC route should be named example.route.bc.

The controller for the BC route should have a deprecated annotation, a deprecation error, and type declarations for any parameters that are required for access checking. Then the body of the controller can use the methods provided by this class:

$change_record = 'https://www.drupal.org/node/3320855';
$helper = new PathChangedHelper($route_match, $request);
$params = [
    '%old_path' => $helper->oldPath(),
    '%new_path' => $helper->newPath(),
    '%change_record' => $change_record,
];
$this->logger
    ->warning('A user was redirected from %old_path. This redirect will be removed in a future version of Drupal. Update links, shortcuts, and bookmarks to use %new_path. See %change_record for more information.', $params);
$message = $this->t('You have been redirected from %old_path. Update links, shortcuts, and bookmarks to use %new_path.', $params);
$this->messenger()
    ->addWarning($message);
return $helper->redirect();

Hierarchy

class \Drupal\Core\Routing\PathChangedHelper

Expanded class hierarchy of PathChangedHelper

File

core/lib/Drupal/Core/Routing/PathChangedHelper.php, line 36

Namespace

Drupal\Core\Routing

View source

class PathChangedHelper {
    
    /**
     * The URL object for the route whose path has changed.
     *
     * @var \Drupal\Core\Url
     */
    protected Url $newUrl;
    
    /**
     * The URL object for the BC route.
     *
     * @var \Drupal\Core\Url
     */
    protected Url $oldUrl;
    
    /**
     * Constructs a PathChangedHelper object.
     *
     * @param \Drupal\Core\Routing\RouteMatchInterface $route_match
     *   A route match object, used for the route name and the parameters.
     * @param \Symfony\Component\HttpFoundation\Request $request
     *   A request object, used for the query parameters.
     *
     * @throws \InvalidArgumentException
     *   The route name from $route_match must end with ".bc".
     */
    public function __construct(RouteMatchInterface $route_match, Request $request) {
        $bc_route_name = $route_match->getRouteName();
        if (!str_ends_with($bc_route_name, '.bc')) {
            throw new \InvalidArgumentException(__CLASS__ . ' expects a route name that ends with ".bc".');
        }
        // Strip '.bc' from the end of the route name.
        $route_name = substr($bc_route_name, 0, -3);
        $args = $route_match->getRawParameters()
            ->all();
        $options = [
            'absolute' => TRUE,
            'query' => array_diff_key($request->query
                ->all(), [
                'destination' => '',
            ]),
        ];
        $this->newUrl = Url::fromRoute($route_name, $args, $options);
        $this->oldUrl = Url::fromRoute($bc_route_name, $args, $options);
    }
    
    /**
     * Returns the deprecated path.
     *
     * @return string
     *   The internal path of the old URL.
     */
    public function oldPath() : string {
        return $this->oldUrl
            ->getInternalPath();
    }
    
    /**
     * Returns the updated path.
     *
     * @return string
     *   The internal path of the new URL.
     */
    public function newPath() : string {
        return $this->newUrl
            ->getInternalPath();
    }
    
    /**
     * Returns a redirect to the new path.
     *
     * @return \Symfony\Component\HttpFoundation\RedirectResponse
     *   A redirect response.
     */
    public function redirect() : RedirectResponse {
        return new RedirectResponse($this->newUrl
            ->toString(), 301);
    }

}

Members

Title Sort descending	Modifiers	Object type	Summary
PathChangedHelper::$newUrl	protected	property	The URL object for the route whose path has changed.
PathChangedHelper::$oldUrl	protected	property	The URL object for the BC route.
PathChangedHelper::newPath	public	function	Returns the updated path.
PathChangedHelper::oldPath	public	function	Returns the deprecated path.
PathChangedHelper::redirect	public	function	Returns a redirect to the new path.
PathChangedHelper::__construct	public	function	Constructs a PathChangedHelper object.