Skip to content

Commit f0415ed

Browse files
TobionTobion
committed
[Routing] made reference type fully BC and improved phpdoc considerably
1 parent 7db07d9 commit f0415ed

File tree

5 files changed

+53
-48
lines changed

5 files changed

+53
-48
lines changed

‎src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,13 @@ class Controller extends ContainerAware
3535
/**
3636
* Generates a URL from the given parameters.
3737
*
38-
* @param string $route The name of the route
39-
* @param mixed $parameters An array of parameters
40-
* @param string $referenceType The type of reference (see UrlGeneratorInterface)
38+
* @param string $route The name of the route
39+
* @param mixed $parameters An array of parameters
40+
* @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
4141
*
4242
* @return string The generated URL
43+
*
44+
* @see UrlGeneratorInterface
4345
*/
4446
public function generateUrl($route, $parameters = array(), $referenceType = UrlGeneratorInterface::ABSOLUTE_PATH)
4547
{

‎src/Symfony/Bundle/FrameworkBundle/Templating/Helper/RouterHelper.php‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,13 @@ public function __construct(UrlGeneratorInterface $router)
3636
/**
3737
* Generates a URL from the given parameters.
3838
*
39-
* @param string $name The name of the route
40-
* @param mixed $parameters An array of parameters
41-
* @param string $referenceType The type of reference (see UrlGeneratorInterface)
39+
* @param string $name The name of the route
40+
* @param mixed $parameters An array of parameters
41+
* @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
4242
*
4343
* @return string The generated URL
44+
*
45+
* @see UrlGeneratorInterface
4446
*/
4547
public function generate($name, $parameters = array(), $referenceType = UrlGeneratorInterface::ABSOLUTE_PATH)
4648
{

‎src/Symfony/Bundle/SecurityBundle/Templating/Helper/LogoutUrlHelper.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,8 @@ public function getLogoutUrl($key)
8181
/**
8282
* Generates the logout URL for the firewall.
8383
*
84-
* @param string $key The firewall key
85-
* @param string $referenceType The type of reference (see UrlGeneratorInterface)
84+
* @param string $key The firewall key
85+
* @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
8686
*
8787
* @return string The logout URL
8888
*

‎src/Symfony/Component/Routing/Generator/UrlGenerator.php‎

Lines changed: 2 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@
1919
use Symfony\Component\HttpKernel\Log\LoggerInterface;
2020

2121
/**
22-
* UrlGenerator generates a URL based on a set of routes.
22+
* UrlGenerator can generate a URL or a path for any route in the RouteCollection
23+
* based on the passed parameters.
2324
*
2425
* @author Fabien Potencier <[email protected]>
2526
* @author Tobias Schultze <http://tobion.de>
@@ -139,37 +140,12 @@ public function generate($name, $parameters = array(), $referenceType = self::AB
139140
return $this->doGenerate($compiledRoute->getVariables(), $route->getDefaults(), $route->getRequirements(), $compiledRoute->getTokens(), $parameters, $name, $referenceType, $compiledRoute->getHostnameTokens());
140141
}
141142

142-
/**
143-
* This method converts the reference type to the new value introduced in Symfony 2.2. It can be used by
144-
* other UrlGenerator implementations to be BC with Symfony 2.1. Reference type was a Boolean called
145-
* $absolute in Symfony 2.1 and only supported two reference types.
146-
*
147-
* @param Boolean $absolute Whether to generate an absolute URL
148-
*
149-
* @return string The new reference type
150-
*
151-
* @deprecated Deprecated since version 2.2, to be removed in 2.3.
152-
*/
153-
public static function convertReferenceType($absolute)
154-
{
155-
if (false === $absolute) {
156-
return self::ABSOLUTE_PATH;
157-
}
158-
if (true === $absolute) {
159-
return self::ABSOLUTE_URL;
160-
}
161-
162-
return $absolute;
163-
}
164-
165143
/**
166144
* @throws MissingMandatoryParametersException When route has some missing mandatory parameters
167145
* @throws InvalidParameterException When a parameter value is not correct
168146
*/
169147
protected function doGenerate($variables, $defaults, $requirements, $tokens, $parameters, $name, $referenceType, $hostnameTokens)
170148
{
171-
$referenceType = self::convertReferenceType($referenceType);
172-
173149
$variables = array_flip($variables);
174150
$mergedParams = array_replace($defaults, $this->context->getParameters(), $parameters);
175151

‎src/Symfony/Component/Routing/Generator/UrlGeneratorInterface.php‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,13 @@
1717
/**
1818
* UrlGeneratorInterface is the interface that all URL generator classes must implement.
1919
*
20+
* The constants in this interface define the different types of resource references that
21+
* are declared in RFC 3986: http://tools.ietf.org/html/rfc3986
22+
* We are using the term "URL" instead of "URI" as this is more common in web applications
23+
* and we do not need to distinguish them as the difference is mostly semantical and
24+
* less technical. Generating URIs, i.e. representation-independent resource identifiers,
25+
* is also possible.
26+
*
2027
* @author Fabien Potencier <[email protected]>
2128
* @author Tobias Schultze <http://tobion.de>
2229
*
@@ -25,27 +32,45 @@
2532
interface UrlGeneratorInterface extends RequestContextAwareInterface
2633
{
2734
/**
28-
* These constants define the different types of resource references that are declared
29-
* in RFC 3986: http://tools.ietf.org/html/rfc3986
30-
* We are using the term "URL" instead of "URI" as this is more common in web applications
31-
* and we do not need to distinguish them as the difference is mostly semantical and
32-
* less technical. Generating URIs, i.e. representation-independent resource identifiers,
33-
* is still possible.
35+
* Generates an absolute URL, e.g. "http://example.com/dir/file".
36+
*/
37+
const ABSOLUTE_URL = true;
38+
39+
/**
40+
* Generates an absolute path, e.g. "/dir/file".
41+
*/
42+
const ABSOLUTE_PATH = false;
43+
44+
/**
45+
* Generates a relative path based on the current request path, e.g. "../parent-file".
46+
* @see UrlGenerator::getRelativePath()
3447
*/
35-
const ABSOLUTE_URL = 'url';
36-
const ABSOLUTE_PATH = 'path';
3748
const RELATIVE_PATH = 'relative';
49+
50+
/**
51+
* Generates a network path, e.g. "//example.com/dir/file".
52+
* Such reference reuses the current scheme but specifies the hostname.
53+
*/
3854
const NETWORK_PATH = 'network';
3955

4056
/**
41-
* Generates a URL from the given parameters.
57+
* Generates a URL or path for a specific route based on the given parameters.
58+
*
59+
* Parameters that reference placeholders in the route pattern will substitute them in the
60+
* path or hostname. Extra params are added as query string to the URL.
61+
*
62+
* When the passed reference type cannot be generated for the route because it requires a different
63+
* hostname or scheme than the current one, the method will return a more comprehensive reference
64+
* that includes the required params. For example, when you call this method with $referenceType = ABSOLUTE_PATH
65+
* but the route requires the https scheme whereas the current scheme is http, it will instead return an
66+
* ABSOLUTE_URL with the https scheme and the current hostname. This makes sure the generated URL matches
67+
* the route in any case.
4268
*
43-
* If the generator is not able to generate the url, it must throw the RouteNotFoundException
44-
* as documented below.
69+
* If there is no route with the given name, the generator must throw the RouteNotFoundException.
4570
*
46-
* @param string $name The name of the route
47-
* @param mixed $parameters An array of parameters
48-
* @param string $referenceType The type of reference to be generated (see defined constants)
71+
* @param string $name The name of the route
72+
* @param mixed $parameters An array of parameters
73+
* @param Boolean|string $referenceType The type of reference to be generated (one of the constants)
4974
*
5075
* @return string The generated URL
5176
*

0 commit comments

Comments
 (0)