1: <?php
 2: 
 3: /*
 4:  * This file is part of the Symfony package.
 5:  *
 6:  * (c) Fabien Potencier <[email protected]>
 7:  *
 8:  * For the full copyright and license information, please view the LICENSE
 9:  * file that was distributed with this source code.
10:  */
11: 
12: namespace Symfony\Component\Routing\Generator;
13: 
14: use Symfony\Component\Routing\Exception\InvalidParameterException;
15: use Symfony\Component\Routing\Exception\MissingMandatoryParametersException;
16: use Symfony\Component\Routing\Exception\RouteNotFoundException;
17: use Symfony\Component\Routing\RequestContextAwareInterface;
18: 
19: /**
20:  * UrlGeneratorInterface is the interface that all URL generator classes must implement.
21:  *
22:  * The constants in this interface define the different types of resource references that
23:  * are declared in RFC 3986: http://tools.ietf.org/html/rfc3986
24:  * We are using the term "URL" instead of "URI" as this is more common in web applications
25:  * and we do not need to distinguish them as the difference is mostly semantical and
26:  * less technical. Generating URIs, i.e. representation-independent resource identifiers,
27:  * is also possible.
28:  *
29:  * @author Fabien Potencier <[email protected]>
30:  * @author Tobias Schultze <http://tobion.de>
31:  */
32: interface UrlGeneratorInterface extends RequestContextAwareInterface
33: {
34:     /**
35:      * Generates an absolute URL, e.g. "http://example.com/dir/file".
36:      */
37:     const ABSOLUTE_URL = 0;
38: 
39:     /**
40:      * Generates an absolute path, e.g. "/dir/file".
41:      */
42:     const ABSOLUTE_PATH = 1;
43: 
44:     /**
45:      * Generates a relative path based on the current request path, e.g. "../parent-file".
46:      *
47:      * @see UrlGenerator::getRelativePath()
48:      */
49:     const RELATIVE_PATH = 2;
50: 
51:     /**
52:      * Generates a network path, e.g. "//example.com/dir/file".
53:      * Such reference reuses the current scheme but specifies the host.
54:      */
55:     const NETWORK_PATH = 3;
56: 
57:     /**
58:      * Generates a URL or path for a specific route based on the given parameters.
59:      *
60:      * Parameters that reference placeholders in the route pattern will substitute them in the
61:      * path or host. Extra params are added as query string to the URL.
62:      *
63:      * When the passed reference type cannot be generated for the route because it requires a different
64:      * host or scheme than the current one, the method will return a more comprehensive reference
65:      * that includes the required params. For example, when you call this method with $referenceType = ABSOLUTE_PATH
66:      * but the route requires the https scheme whereas the current scheme is http, it will instead return an
67:      * ABSOLUTE_URL with the https scheme and the current host. This makes sure the generated URL matches
68:      * the route in any case.
69:      *
70:      * If there is no route with the given name, the generator must throw the RouteNotFoundException.
71:      *
72:      * @param string $name          The name of the route
73:      * @param mixed  $parameters    An array of parameters
74:      * @param int    $referenceType The type of reference to be generated (one of the constants)
75:      *
76:      * @return string The generated URL
77:      *
78:      * @throws RouteNotFoundException              If the named route doesn't exist
79:      * @throws MissingMandatoryParametersException When some parameters are missing that are mandatory for the route
80:      * @throws InvalidParameterException           When a parameter value for a placeholder is not correct because
81:      *                                             it does not match the requirement
82:      */
83:     public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH);
84: }
85: