class PathChangedHelper

Same name in other branches
  1. 10 core/lib/Drupal/Core/Routing/PathChangedHelper.php \Drupal\Core\Routing\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

Expanded class hierarchy of PathChangedHelper

2 files declare their use of PathChangedHelper
PathChangedHelperTest.php in core/tests/Drupal/KernelTests/Core/Routing/PathChangedHelperTest.php
PathChangedHelperTest.php in core/tests/Drupal/Tests/Core/Routing/PathChangedHelperTest.php

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 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.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.