Chris@0: Chris@0: * Chris@0: * For the full copyright and license information, please view the LICENSE Chris@0: * file that was distributed with this source code. Chris@0: */ Chris@0: Chris@0: namespace Symfony\Component\Routing\Generator; Chris@0: Chris@0: use Symfony\Component\Routing\Exception\InvalidParameterException; Chris@0: use Symfony\Component\Routing\Exception\MissingMandatoryParametersException; Chris@0: use Symfony\Component\Routing\Exception\RouteNotFoundException; Chris@0: use Symfony\Component\Routing\RequestContextAwareInterface; Chris@0: Chris@0: /** Chris@0: * UrlGeneratorInterface is the interface that all URL generator classes must implement. Chris@0: * Chris@0: * The constants in this interface define the different types of resource references that Chris@0: * are declared in RFC 3986: http://tools.ietf.org/html/rfc3986 Chris@0: * We are using the term "URL" instead of "URI" as this is more common in web applications Chris@0: * and we do not need to distinguish them as the difference is mostly semantical and Chris@0: * less technical. Generating URIs, i.e. representation-independent resource identifiers, Chris@0: * is also possible. Chris@0: * Chris@0: * @author Fabien Potencier Chris@0: * @author Tobias Schultze Chris@0: */ Chris@0: interface UrlGeneratorInterface extends RequestContextAwareInterface Chris@0: { Chris@0: /** Chris@0: * Generates an absolute URL, e.g. "http://example.com/dir/file". Chris@0: */ Chris@0: const ABSOLUTE_URL = 0; Chris@0: Chris@0: /** Chris@0: * Generates an absolute path, e.g. "/dir/file". Chris@0: */ Chris@0: const ABSOLUTE_PATH = 1; Chris@0: Chris@0: /** Chris@0: * Generates a relative path based on the current request path, e.g. "../parent-file". Chris@0: * Chris@0: * @see UrlGenerator::getRelativePath() Chris@0: */ Chris@0: const RELATIVE_PATH = 2; Chris@0: Chris@0: /** Chris@0: * Generates a network path, e.g. "//example.com/dir/file". Chris@0: * Such reference reuses the current scheme but specifies the host. Chris@0: */ Chris@0: const NETWORK_PATH = 3; Chris@0: Chris@0: /** Chris@0: * Generates a URL or path for a specific route based on the given parameters. Chris@0: * Chris@0: * Parameters that reference placeholders in the route pattern will substitute them in the Chris@0: * path or host. Extra params are added as query string to the URL. Chris@0: * Chris@0: * When the passed reference type cannot be generated for the route because it requires a different Chris@0: * host or scheme than the current one, the method will return a more comprehensive reference Chris@0: * that includes the required params. For example, when you call this method with $referenceType = ABSOLUTE_PATH Chris@0: * but the route requires the https scheme whereas the current scheme is http, it will instead return an Chris@0: * ABSOLUTE_URL with the https scheme and the current host. This makes sure the generated URL matches Chris@0: * the route in any case. Chris@0: * Chris@0: * If there is no route with the given name, the generator must throw the RouteNotFoundException. Chris@0: * Chris@0: * The special parameter _fragment will be used as the document fragment suffixed to the final URL. Chris@0: * Chris@0: * @param string $name The name of the route Chris@0: * @param mixed $parameters An array of parameters Chris@0: * @param int $referenceType The type of reference to be generated (one of the constants) Chris@0: * Chris@0: * @return string The generated URL Chris@0: * Chris@0: * @throws RouteNotFoundException If the named route doesn't exist Chris@0: * @throws MissingMandatoryParametersException When some parameters are missing that are mandatory for the route Chris@0: * @throws InvalidParameterException When a parameter value for a placeholder is not correct because Chris@0: * it does not match the requirement Chris@0: */ Chris@17: public function generate($name, $parameters = [], $referenceType = self::ABSOLUTE_PATH); Chris@0: }