[Routing] made reference type fully BC and improved phpdoc considerably

symfony · Tobion · Apr 16, 2012 · Dec 13, 2012 · Dec 13, 2012 · Dec 13, 2012
commit 2114972bea74c440cfd23340e965ea5c1772ff70
diff --git a/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php b/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
@@ -35,11 +35,13 @@ class Controller extends ContainerAware
     /**
      * Generates a URL from the given parameters.
      *
-     * @param string $route         The name of the route
-     * @param mixed  $parameters    An array of parameters
-     * @param string $referenceType The type of reference (see UrlGeneratorInterface)
+     * @param string         $route         The name of the route
+     * @param mixed          $parameters    An array of parameters
+     * @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
      *
      * @return string The generated URL
+     *
+     * @see UrlGeneratorInterface
      */
     public function generateUrl($route, $parameters = array(), $referenceType = UrlGeneratorInterface::ABSOLUTE_PATH)
     {

diff --git a/src/Symfony/Bundle/FrameworkBundle/Templating/Helper/RouterHelper.php b/src/Symfony/Bundle/FrameworkBundle/Templating/Helper/RouterHelper.php
@@ -36,11 +36,13 @@ public function __construct(UrlGeneratorInterface $router)
     /**
      * Generates a URL from the given parameters.
      *
-     * @param string $name          The name of the route
-     * @param mixed  $parameters    An array of parameters
-     * @param string $referenceType The type of reference (see UrlGeneratorInterface)
+     * @param string         $name          The name of the route
+     * @param mixed          $parameters    An array of parameters
+     * @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
      *
      * @return string The generated URL
+     *
+     * @see UrlGeneratorInterface
      */
     public function generate($name, $parameters = array(), $referenceType = UrlGeneratorInterface::ABSOLUTE_PATH)
     {

diff --git a/src/Symfony/Bundle/SecurityBundle/Templating/Helper/LogoutUrlHelper.php b/src/Symfony/Bundle/SecurityBundle/Templating/Helper/LogoutUrlHelper.php
@@ -81,8 +81,8 @@ public function getLogoutUrl($key)
     /**
      * Generates the logout URL for the firewall.
      *
-     * @param string $key           The firewall key
-     * @param string $referenceType The type of reference (see UrlGeneratorInterface)
+     * @param string         $key           The firewall key
+     * @param Boolean|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
      *
      * @return string The logout URL
      *

diff --git a/src/Symfony/Component/Routing/Generator/UrlGenerator.php b/src/Symfony/Component/Routing/Generator/UrlGenerator.php
@@ -19,7 +19,8 @@
 use Symfony\Component\HttpKernel\Log\LoggerInterface;
 
 /**
- * UrlGenerator generates a URL based on a set of routes.
+ * UrlGenerator can generate a URL or a path for any route in the RouteCollection
+ * based on the passed parameters.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  * @author Tobias Schultze <http://tobion.de>
@@ -139,37 +140,12 @@ public function generate($name, $parameters = array(), $referenceType = self::AB
         return $this->doGenerate($compiledRoute->getVariables(), $route->getDefaults(), $route->getRequirements(), $compiledRoute->getTokens(), $parameters, $name, $referenceType, $compiledRoute->getHostnameTokens());
     }
 
-    /**
-     * This method converts the reference type to the new value introduced in Symfony 2.2. It can be used by
-     * other UrlGenerator implementations to be BC with Symfony 2.1. Reference type was a Boolean called
-     * $absolute in Symfony 2.1 and only supported two reference types.
-     *
-     * @param Boolean $absolute Whether to generate an absolute URL
-     *
-     * @return string The new reference type
-     *
-     * @deprecated Deprecated since version 2.2, to be removed in 2.3.
-     */
-    public static function convertReferenceType($absolute)
-    {
-        if (false === $absolute) {
-            return self::ABSOLUTE_PATH;
-        }
-        if (true === $absolute) {
-            return self::ABSOLUTE_URL;
-        }
-
-        return $absolute;
-    }
-
     /**
      * @throws MissingMandatoryParametersException When route has some missing mandatory parameters
      * @throws InvalidParameterException When a parameter value is not correct
      */
     protected function doGenerate($variables, $defaults, $requirements, $tokens, $parameters, $name, $referenceType, $hostnameTokens)
     {
-        $referenceType = self::convertReferenceType($referenceType);
-
         $variables = array_flip($variables);
         $mergedParams = array_replace($defaults, $this->context->getParameters(), $parameters);
 

diff --git a/src/Symfony/Component/Routing/Generator/UrlGeneratorInterface.php b/src/Symfony/Component/Routing/Generator/UrlGeneratorInterface.php
@@ -17,6 +17,13 @@
 /**
  * UrlGeneratorInterface is the interface that all URL generator classes must implement.
  *
+ * The constants in this interface define the different types of resource references that
+ * are declared in RFC 3986: http://tools.ietf.org/html/rfc3986
+ * We are using the term "URL" instead of "URI" as this is more common in web applications
+ * and we do not need to distinguish them as the difference is mostly semantical and
+ * less technical. Generating URIs, i.e. representation-independent resource identifiers,
+ * is also possible.
+ *
  * @author Fabien Potencier <fabien@symfony.com>
  * @author Tobias Schultze <http://tobion.de>
  *
@@ -25,27 +32,45 @@
 interface UrlGeneratorInterface extends RequestContextAwareInterface
 {
     /**
-     * These constants define the different types of resource references that are declared
-     * in RFC 3986: http://tools.ietf.org/html/rfc3986
-     * We are using the term "URL" instead of "URI" as this is more common in web applications
-     * and we do not need to distinguish them as the difference is mostly semantical and
-     * less technical. Generating URIs, i.e. representation-independent resource identifiers,
-     * is still possible.
+     * Generates an absolute URL, e.g. "http://example.com/dir/file".
+     */
+    const ABSOLUTE_URL = true;
+
+    /**
+     * Generates an absolute path, e.g. "/dir/file".
+     */
+    const ABSOLUTE_PATH = false;
+
+    /**
+     * Generates a relative path based on the current request path, e.g. "../parent-file".
+     * @see UrlGenerator::getRelativePath()
      */
-    const ABSOLUTE_URL = 'url';
-    const ABSOLUTE_PATH = 'path';
     const RELATIVE_PATH = 'relative';
+
+    /**
+     * Generates a network path, e.g. "//example.com/dir/file".
+     * Such reference reuses the current scheme but specifies the hostname.
+     */
     const NETWORK_PATH = 'network';
 
     /**
-     * Generates a URL from the given parameters.
+     * Generates a URL or path for a specific route based on the given parameters.
+     *
+     * Parameters that reference placeholders in the route pattern will substitute them in the
+     * path or hostname. Extra params are added as query string to the URL.
+     *
+     * When the passed reference type cannot be generated for the route because it requires a different
+     * hostname or scheme than the current one, the method will return a more comprehensive reference
+     * that includes the required params. For example, when you call this method with $referenceType = ABSOLUTE_PATH
+     * but the route requires the https scheme whereas the current scheme is http, it will instead return an
+     * ABSOLUTE_URL with the https scheme and the current hostname. This makes sure the generated URL matches
+     * the route in any case.
      *
-     * If the generator is not able to generate the url, it must throw the RouteNotFoundException
-     * as documented below.
+     * If there is no route with the given name, the generator must throw the RouteNotFoundException.
      *
-     * @param string $name          The name of the route
-     * @param mixed  $parameters    An array of parameters
-     * @param string $referenceType The type of reference to be generated (see defined constants)
+     * @param string         $name          The name of the route
+     * @param mixed          $parameters    An array of parameters
+     * @param Boolean|string $referenceType The type of reference to be generated (one of the constants)
      *
      * @return string The generated URL
      *