feature #16276 Unify URL generator reference type + make linking in p…

…hp templates consistent with twig (Tobion)

This PR was merged into the 2.8 branch.

Discussion
----------

Unify URL generator reference type + make linking in php templates consistent with twig

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #14672
| License       | MIT
| Doc PR        | TODO

Please see ticket.
Please merge #16277 first. I will then rebase this to make tests pass.

Commits
-------

388fa43 [Templating] deprecate low-level RouterHelper::generate method as it's cumbersome to use constants in templates
97d6828 [Templating] introduce path and url methods in php templates to be in line with twig templates
912fc4d [Routing] deprecate the old url generator reference type values

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

@@ -39,9 +39,9 @@ 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 bool|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
+     * @param string $route         The name of the route
+     * @param mixed  $parameters    An array of parameters
+     * @param int    $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
      *
      * @return string The generated URL
      *

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

@@ -36,19 +36,53 @@ 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 bool|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
+     * @param string $name          The name of the route
+     * @param mixed  $parameters    An array of parameters
+     * @param int    $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)
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated since version 2.8 and will be removed in 3.0. Use the "path" or "url" method instead.', E_USER_DEPRECATED);
+
         return $this->generator->generate($name, $parameters, $referenceType);
     }
 
+    /**
+     * Generates a URL reference (as an absolute or relative path) to the route with the given parameters.
+     *
+     * @param string $name       The name of the route
+     * @param mixed  $parameters An array of parameters
+     * @param bool   $relative   Whether to generate a relative or absolute path
+     *
+     * @return string The generated URL reference
+     *
+     * @see UrlGeneratorInterface
+     */
+    public function path($name, $parameters = array(), $relative = false)
+    {
+        return $this->generator->generate($name, $parameters, $relative ? UrlGeneratorInterface::RELATIVE_PATH : UrlGeneratorInterface::ABSOLUTE_PATH);
+    }
+
+    /**
+     * Generates a URL reference (as an absolute URL or network path) to the route with the given parameters.
+     *
+     * @param string $name           The name of the route
+     * @param mixed  $parameters     An array of parameters
+     * @param bool   $schemeRelative Whether to omit the scheme in the generated URL reference
+     *
+     * @return string The generated URL reference
+     *
+     * @see UrlGeneratorInterface
+     */
+    public function url($name, $parameters = array(), $schemeRelative = false)
+    {
+        return $this->generator->generate($name, $parameters, $schemeRelative ? UrlGeneratorInterface::NETWORK_PATH : UrlGeneratorInterface::ABSOLUTE_URL);
+    }
+
     /**
      * {@inheritdoc}
      */

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

@@ -143,6 +143,20 @@ public function generate($name, $parameters = array(), $referenceType = self::AB
      */
     protected function doGenerate($variables, $defaults, $requirements, $tokens, $parameters, $name, $referenceType, $hostTokens, array $requiredSchemes = array())
     {
+        if (is_bool($referenceType) || is_string($referenceType)) {
+            @trigger_error('The hardcoded value you are using for the $referenceType argument of the '.__CLASS__.'::generate method is deprecated since version 2.8 and will not be supported anymore in 3.0. Use the constants defined in the UrlGeneratorInterface instead.', E_USER_DEPRECATED);
+
+            if (true === $referenceType) {
+                $referenceType = self::ABSOLUTE_URL;
+            } elseif (false === $referenceType) {
+                $referenceType = self::ABSOLUTE_PATH;
+            } elseif ('relative' === $referenceType) {
+                $referenceType = self::RELATIVE_PATH;
+            } elseif ('network' === $referenceType) {
+                $referenceType = self::NETWORK_PATH;
+            }
+        }
+
         $variables = array_flip($variables);
         $mergedParams = array_replace($defaults, $this->context->getParameters(), $parameters);
 

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

@@ -34,25 +34,25 @@ interface UrlGeneratorInterface extends RequestContextAwareInterface
     /**
      * Generates an absolute URL, e.g. "http://example.com/dir/file".
      */
-    const ABSOLUTE_URL = true;
+    const ABSOLUTE_URL = 0;
 
     /**
      * Generates an absolute path, e.g. "/dir/file".
      */
-    const ABSOLUTE_PATH = false;
+    const ABSOLUTE_PATH = 1;
 
     /**
      * Generates a relative path based on the current request path, e.g. "../parent-file".
      *
      * @see UrlGenerator::getRelativePath()
      */
-    const RELATIVE_PATH = 'relative';
+    const RELATIVE_PATH = 2;
 
     /**
      * Generates a network path, e.g. "//example.com/dir/file".
      * Such reference reuses the current scheme but specifies the host.
      */
-    const NETWORK_PATH = 'network';
+    const NETWORK_PATH = 3;
 
     /**
      * Generates a URL or path for a specific route based on the given parameters.
@@ -69,9 +69,9 @@ interface UrlGeneratorInterface extends RequestContextAwareInterface
      *
      * 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 bool|string $referenceType The type of reference to be generated (one of the constants)
+     * @param string $name          The name of the route
+     * @param mixed  $parameters    An array of parameters
+     * @param int    $referenceType The type of reference to be generated (one of the constants)
      *
      * @return string The generated URL
      *

src/Symfony/Component/Security/Http/Logout/LogoutUrlGenerator.php

@@ -86,7 +86,7 @@ public function getLogoutUrl($key = null)
      * Generates the logout URL for the firewall.
      *
      * @param string|null $key           The firewall key or null to use the current firewall key
-     * @param bool|string $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
+     * @param int         $referenceType The type of reference (one of the constants in UrlGeneratorInterface)
      *
      * @return string The logout URL
      *