[Routing] add support for path-relative and scheme-relative URL generation
[Routing] added tests for generating relative paths and network paths
[Routing] made reference type fully BC and improved phpdoc considerably
fix phpdoc of UrlGeneratorInterface that missed some exceptions and improve language of exception message
added changelog entries
[Monolog] Mark old non-PSR3 methods as deprecated
merged branch Tobion/relative-path (PR #3958)

This PR was merged into the master branch.

Commits
-------

6703fb5 added changelog entries
1997e2e fix phpdoc of UrlGeneratorInterface that missed some exceptions and improve language of exception message
f0415ed [Routing] made reference type fully BC and improved phpdoc considerably
7db07d9 [Routing] added tests for generating relative paths and network paths
75f59eb [Routing] add support for path-relative and scheme-relative URL generation

Discussion
----------

[2.2] [Routing] add support for path-relative URL generation

Tests pass: yes
Feature addition: yes
BC break: <del>tiny (see below)</del> NO
deprecations: NO

At the moment the Routing component only supports absolute and domain-relative URLs, e.g.
`http://example.org/user-slug/article-slug/comments` and
`/user-slug/article-slug/comments`.

But there are two link types missing: schema-relative URLs and path-relative URLs.
schema-relative: e.g. `//example.org/user-slug/article-slug/comments`
path-relative: e.g. `comments`.

Both of them would now be possible with this PR. I think it closes a huge gap in the Routing component.
Use cases are pretty common. Schema-relative URLs are for example used when you want to include assets (scripts, images etc) in a secured website with HTTPS. Path-relative URLs are the only option when you want to generate static files (e.g. documentation) that can be downloaded as an HTML archive. Such use-cases are currently not possible with symfony.

The calculation of the relative path based on the request path and target path is hightly unit tested. So it is really equivalent. I found several implemenations on the internet but none of them worked in all cases. Mine is pretty short and works.

I also added an optional parameter to the twig `path` function, so this feature can also be used in twig templates.

Ref: This implements path-relative URLs as suggested in #3908.

<del>[BC BREAK] The signature of UrlGeneratorInterface::generate changed to support scheme-relative and path-relative URLs. The core UrlGenerator is BC and does not break anything, but users who implemented their own UrlGenerator need to be aware of this change. See UrlGenerator::convertReferenceType.</del>

---------------------------------------------------------------------------

by jalliot at 2012-04-16T09:56:56Z

@Tobion For completeness, you should add the option to the `url` and `asset` twig functions/template helpers.

---------------------------------------------------------------------------

by stof at 2012-04-16T10:46:06Z

@jalliot adding the option to ``url`` does not make any sense. The difference between ``path`` and ``url`` is that ``path`` generates a path and ``url`` generates an absolute url (thus including the scheme and the hostname)

---------------------------------------------------------------------------

by Tobion at 2012-04-16T12:27:49Z

@stof I guess jalliot meant we could then generate scheme-relative URLs with `url`. Otherwise this would have no equivalent in twig.

---------------------------------------------------------------------------

by jalliot at 2012-04-16T12:34:08Z

@stof Yep I meant what @Tobion said :)

---------------------------------------------------------------------------

by Tobion at 2012-04-18T11:57:04Z

The $relative parameter I added besides the existing $absolute parameter of the `->generate` method was not clear enough. So I merged those into a different parameter `referenceType`. I adjusted all parts of symfony to use the new signature. And also made the default `UrlGenerator` implementation BC with the old style. So almost nobody will recognize a change. The only BC break would be for somebody who implemented his own `UrlGenerator` and did not call the parent default generator.
Using `referenceType` instead of a simple Boolean is much more flexible. It will for example allow a custom generator to support a new reference type like http://en.wikipedia.org/wiki/CURIE

---------------------------------------------------------------------------

by Tobion at 2012-04-18T13:34:58Z

ping @schmittjoh considering your https://github.com/schmittjoh/JMSI18nRoutingBundle/blob/master/Router/I18nRouter.php would need a tiny change

---------------------------------------------------------------------------

by schmittjoh at 2012-04-18T13:37:39Z

Can you elaborate the necessary change?

---------------------------------------------------------------------------

by Tobion at 2012-04-18T13:51:10Z

This PR changes the signature of `generate` to be able to generate path-relative and scheme-relative URLs. So it needs to be
`public function generate($name, $parameters = array(), $referenceType = self::ABSOLUTE_PATH)` and your implementation would need to change `if ($absolute && $this->hostMap) {` to `if (self::ABSOLUTE_URL === $referenceType && $this->hostMap) {`
I can do a PR if this gets merged.

---------------------------------------------------------------------------

by schmittjoh at 2012-04-18T13:52:14Z

If I understand correctly, the old parameter still works, no?

edit: Ah, ok I see what you mean now.

---------------------------------------------------------------------------

by Tobion at 2012-04-18T13:56:33Z

Yeah the old parameter still works but $absolute would also evaluate to true (a string) in your case for non-absolute URLs, i.e. paths.

---------------------------------------------------------------------------

by Tobion at 2012-04-19T21:09:46Z

ping @fabpot

---------------------------------------------------------------------------

by fabpot at 2012-04-20T04:30:18Z

Let's discuss that feature for 2.2.

---------------------------------------------------------------------------

by Tobion at 2012-04-20T10:40:59Z

What are your objections against it? It's already implemented, it works and it adds support for things that are part of a web standard. The BC break is tiny at the moment (almost nobody is affected) because the core UrlGenerator works as before. But if we waited for 2.2 it will be much harder to make the transition because 2.1 is LTS. So I think is makes sense to add it now. Furthermore it makes it much more future-proof as custom generators can more easiliy add support for other link types like CURIE. At the moment a Boolean for absolute URLs is simply too limited and also somehow inconsistent because $absolute = false stands for an absolute path. You see the awkwardness in this naming.

Btw, I added a note in the changelog. And I will add documentation of this feature in symfony-docs once this is merged.

---------------------------------------------------------------------------

by fabpot at 2012-04-20T12:14:32Z

nobody has ever said that 2.1 would be LTS. Actually, I think we are going to wait for 2.3 for LTS.

---------------------------------------------------------------------------

by Tobion at 2012-04-20T12:27:18Z

Well what I meant is, the longer we wait with this, the harder to apply it.
In 04ac1fdba2498 you modified `generate` signature for better extensibility that is not even made use of. I think changing `$abolute` param goes in the same direction and has direct use.

I'd like to know your reason to wait for 2.2. Not enough time to review it, or afraid of breaking something, or marketing for 2.2?

---------------------------------------------------------------------------

by stof at 2012-04-20T16:28:27Z

@Tobion the issue is that merging new features forces to postpone the release so that it is tested by enough devs first to be sure there is no blocking bug in it. Big changes cannot be merged when we are hunting the remaining bugs to be able to release.

---------------------------------------------------------------------------

by schmittjoh at 2012-04-20T16:42:11Z

Considering the changes that have been made to the Form component, and are still being made, I think this is in comparison to that a fairly minor change.

Maybe a clearer guideline on the release process, or the direction would help, and avoid confusion, or wrong expectations on contributors' part.

---------------------------------------------------------------------------

by Tobion at 2012-10-05T13:52:11Z

@fabpot this is ready. So if you agree with it, I would create a documentation PR.

---------------------------------------------------------------------------

by stof at 2012-10-13T16:09:47Z

@fabpot what do you think about this PR ?

---------------------------------------------------------------------------

by Crell at 2012-11-01T16:05:01Z

This feels like it's overloading the generate() method to do double duty: One, make a URl based on a route.  Two, make a  URI based on a URI snippet.  Those are two separate operations.  Why not just add a second method that does the second operation and avoid the conditionals?  (We're likely to do that in Drupal for our own generator as well.)

---------------------------------------------------------------------------

by Tobion at 2012-11-01T16:38:39Z

@crell: No, you must have misunderstood something. The generate method still only generates a URI based on a route. The returned URI reference can now also be a relative path and a network path. Thats all.

---------------------------------------------------------------------------

by Tobion at 2012-12-13T18:30:28Z

@fabpot this is ready. It is fully BC! I also improved phpdoc considerably.

---------------------------------------------------------------------------

by Tobion at 2012-12-14T20:51:38Z

@fabpot Do you want me to write documentation for it? I would also be interested to write about the new features of the routing component in general. I wanted to do that anyway and it would probably be a good fit for your "new in symfony" articles.

---------------------------------------------------------------------------

by fabpot at 2012-12-14T20:58:16Z

Im' going to review this PR in the next coming days. And to answer your second question, more documentation or better documentation is always a good thing, so go for it.

---------------------------------------------------------------------------

by Tobion at 2013-01-02T21:50:20Z

@fabpot ping. I added changelog entries.
Remove use of deprecated HttpKernel LoggerInterface
merged branch Seldaek/psr3 (PR #6628)

This PR was merged into the master branch.

Commits
-------

67d7423 Remove use of deprecated HttpKernel LoggerInterface
dca4528 [HttpKernel] Extend psr/log's NullLogger class
1e5a890 [Monolog] Mark old non-PSR3 methods as deprecated
91a86f8 [HttpKernel][Monolog] Add PSR-3 support to the LoggerInterface

Discussion
----------

[HttpKernel][MonologBridge] PSR-3 support

This enables PSR-3 support and monolog 1.3+. The first commit is the main part. The rest deals with deprecation of short-hand methods (warn/err/crit/emerg) that are fully expanded in PSR-3 (warning/error/critical/emergency).

The downside of deprecating them is that for bundles it's a bit harder to support older and newer versions. If that is too much of a hassle you can drop that for now and cherry pick the first commit.

The upside is that it forces people to move towards PSR-3 compatible stuff, which means eventually we could completely drop the LoggerInterface from the framework. In any case I think the documentation should only mention the `Psr\Log\LoggerInterface` and people should start hinting against that. The change should be done in core as well I suppose.

Anyway I wanted to throw this out there as it is to get feedback.

---------------------------------------------------------------------------

by stof at 2013-01-09T09:15:15Z

@Seldaek I also think you should change the typehint to use the PSR LoggerInterface in all classes using the logger

---------------------------------------------------------------------------

by Seldaek at 2013-01-09T09:54:55Z

OK updated according to all the feedback. I tested it in an app and it still seems to work so there shouldn't be any major issues.

---------------------------------------------------------------------------

by Seldaek at 2013-01-09T09:59:55Z

@fabpot if you merge please merge also the bundle PR, otherwise it won't be possible to update without conflict.

---------------------------------------------------------------------------

by frosas at 2013-01-10T14:59:20Z

I'm trying to understand why a `composer update` of a Symfony 2.1.* resulted in a fatal error. Shouldn't a stable version don't break like this?

As @olaurendeau points, why Symfony depends 1.* instead of 1.2.*? Or why Monolog 1.3 breaks its public interface (EDIT: I'm not sure about it)? Or why isn't this PR being merged (into branch 2.1) at the same time Monolog 1.3 is released?

Please, understand I'm not looking for who to blame, it's just I want to know if this situation is unexpected or if otherwise a `composer update` on a stable branch is not as innocent as it seems.

---------------------------------------------------------------------------

by stof at 2013-01-10T15:06:51Z

@frosas it cannot be merged into 2.1 as it is a BC break. The 2.1 branch has been updated to forbid Monolog 1.3 already

---------------------------------------------------------------------------

by Seldaek at 2013-01-10T15:11:58Z

@frosas you can blame me for releasing as 1.3.0 and not 2.0, but technically for monolog this isn't really a BC break, I just added an interface. The problem is due to the way it's used in symfony, it ended up as a fatal error. In any case the situation is now sorted out I think.

---------------------------------------------------------------------------

by frosas at 2013-01-10T15:26:43Z

@stof now I see this `>=1.0,<1.3-dev` change in the 2.1 branch. Now, shouldn't a new (2.1.7) version be released for all of us not in the dev minimum-stability?

@Seldaek then do you see feasible to rely only in X.Y.* versions to avoid this kind of errors?

---------------------------------------------------------------------------

by Seldaek at 2013-01-10T15:45:22Z

@frosas relying on X.Y.* is painful because you always need to wait until someone updates the constraint to get the new version. Of course using ~1.3 like in this PR means if I fuck up and break BC people will update to it, but that's a less likely occurrence than the alternative I think, so I would rather not use X.Y.*

---------------------------------------------------------------------------

by frosas at 2013-01-10T15:50:50Z

@Seldaek you are right about this, but I was thinking more in changing it only for the stable versions. EDIT: I mean, how often do you need a new feature in a branch you only apply fixes to?

---------------------------------------------------------------------------

by stof at 2013-01-10T15:57:32Z

@frosas Monolog and Symfony have separate release cycles. Foorcing Symfony users to use an old version of Monolog until they update to a new version of Symfony whereas the newer Monolog is compatible is a bad idea. Thus, as Monolog keeps BC, it does not maintain bugfix releases for all older versions (just like Twig does too). So it would also forbid you to get the fixes done in newer Monolog versions.

The incompatibility between Symfony 2.1 LoggerInterface and PSR-3 (whereas they expect exactly the same behavior and signature for methods with the same name) is unfortunate and is the reason why we get some issues here.

---------------------------------------------------------------------------

by frosas at 2013-01-10T16:21:06Z

@stof I appreciate you prefer to allow newer versions at the price of having to be constantly monitoring its changes to avoid breaks.

Another similar but safer strategy would be to stick to X.Y.* versions and upgrade to X.Y+1.* once the new version integration is tested, but I understand this is discutible in projects as close to Symfony as Monolog.

Returning to the issue, what do you say to release this 2.1.7 version? Or is it only me who is having issues here?

---------------------------------------------------------------------------

by stof at 2013-01-10T16:26:20Z

@frosas a minor release should not break BC when following smeantic versionning (Symfony warned about the fact it is not strictly followed for the first releases of 2.x). But as far as monolog is concerned, 1.3 is BC with 1.2.

---------------------------------------------------------------------------

by Seldaek at 2013-01-10T16:49:55Z

@frosas sorry I didn't get you still had the problem. I tagged a 2.1.7 of monologbundle which hopefully fixes your issue.