RouteMatchInterface.php

<?php

namespace Drupal\Core\Routing;


/**
 * Provides an interface for classes representing the result of routing.
 *
 * Routing is the process of selecting the best matching candidate from a
 * collection of routes for an incoming request. The relevant properties of a
 * request include the path as well as a list of raw parameter values derived
 * from the URL. If an appropriate route is found, raw parameter values will be
 * upcast automatically if possible.
 *
 * The route match object contains useful information about the selected route
 * as well as the raw and upcast parameters derived from the incoming
 * request.
 *
 * @ingroup routing
 */
interface RouteMatchInterface {

  /**
   * Returns the route name.
   *
   * @return string|null
   *   The route name. NULL if no route is matched.
   */
  public function getRouteName();

  /**
   * Returns the route object.
   *
   * @return \Symfony\Component\Routing\Route|null
   *   The route object. NULL if no route is matched.
   */
  public function getRouteObject();

  /**
   * Returns the processed value of a named route parameter.
   *
   * Raw URL parameters are processed by the parameter conversion system, which
   * does operations such as converting entity ID parameters to fully-loaded
   * entities. For example, the path node/12345 would have a raw node ID
   * parameter value of 12345, while the processed parameter value would be the
   * corresponding loaded node object.
   *
   * @param string $parameter_name
   *   The parameter name.
   *
   * @return mixed|null
   *   The parameter value. NULL if the route doesn't define the parameter or
   *   if the parameter value can't be determined from the request.
   *
   * @see \Drupal\Core\Routing\RouteMatchInterface::getRawParameter()
   */
  public function getParameter($parameter_name);

  /**
   * Returns the bag of all processed route parameters.
   *
   * Raw URL parameters are processed by the parameter conversion system, which
   * does operations such as converting entity ID parameters to fully-loaded
   * entities. For example, the path node/12345 would have a raw node ID
   * parameter value of 12345, while the processed parameter value would be the
   * corresponding loaded node object.
   *
   * @return \Symfony\Component\HttpFoundation\ParameterBag
   *   The parameter bag.
   *
   * @see \Drupal\Core\Routing\RouteMatchInterface::getRawParameters()
   */
  public function getParameters();

  /**
   * Returns the raw value of a named route parameter.
   *
   * @param string $parameter_name
   *   The parameter name.
   *
   * @return string|null
   *   The raw (non-upcast) parameter value. NULL if the route doesn't define
   *   the parameter or if the raw parameter value can't be determined from the
   *   request.
   *
   * @see \Drupal\Core\Routing\RouteMatchInterface::getParameter()
   */
  public function getRawParameter($parameter_name);

  /**
   * Returns the bag of all raw route parameters.
   *
   * @return \Symfony\Component\HttpFoundation\ParameterBag
   *   The parameter bag.
   *
   * @see \Drupal\Core\Routing\RouteMatchInterface::getParameters()
   */
  public function getRawParameters();

}