This PR was merged into the master branch.
Commits
-------
9fc7def added the UPGRADE file for Symfony 3.0
e84cad2 [Routing] updated CHANGELOG
65eca8a [Routing] added new schemes and methods options to the annotation loader
5082994 [Routing] renamed pattern to path
b357caf [Routing] renamed hostname pattern to just hostname
e803f46 made schemes and methods available in XmlFileLoader
d374e70 made schemes and methods available in YamlFileLoader
2834e7e added scheme and method setter in RouteCollection
10183de make scheme and method requirements first-class citizen in Route
Discussion
----------
Routing options
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | no
| BC breaks? | no
| Deprecations? | yes
| Tests pass? | yes
| Fixed tickets | #5989, #5990, #6049
| License | MIT
In #5989, it has unanimously been decided to renamed `hostname_pattern` to `hostname` and `pattern` to `path`. That makes a lot of sense and I would like to do the renaming now as `hostname_pattern` is new in Symfony 2.2, so I'd like to avoid breaking BC just after the release. As we are modifying the route options, I've also included changes introduced by @Tobion in #6049 which were discussed in #5990.
As everything is BC, I think it's wise to include that in 2.2. What do you think?
---------------------------------------------------------------------------
by Tobion at 2013-01-14T18:25:53Z
I agree it should be done in 2.2. Thanks for working on it.
---------------------------------------------------------------------------
by vicb at 2013-01-14T23:11:12Z
@fabpot "Everything is BC" until it breaks BC in 3.0, that's why I'd like to see [deprecations in PR summary](https://github.com/symfony/symfony-docs/pull/2116) what do you think ?
---------------------------------------------------------------------------
by vicb at 2013-01-14T23:16:40Z
it would also be great to update the CHANGELOG with deprecations (it could also help people answering your question)
---------------------------------------------------------------------------
by fabpot at 2013-01-15T07:07:03Z
@vicb: I've just updated the CHANGELOG and created the UPGRADE file for 3.0.
---------------------------------------------------------------------------
by vicb at 2013-01-15T07:15:32Z
@fabpot thanks.
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 04ac1fdba2 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.
This PR was merged into the master branch.
Commits
-------
51223c0 added upgrade instructions
50e6259 adjusted tests
98f3ca8 [Routing] removed tree structure from RouteCollection
Discussion
----------
[Routing] removed tree structure from RouteCollection
BC break: yes (see below)
Deprecations: RouteCollection::getParent(); RouteCollection::getRoot()
tests pass: yes
The reason for this is so quite simple. The RouteCollection has been designed as a tree structure, but it cannot at all be used as one. There is no getter for a sub-collection at all. So you cannot access a sub-collection after you added it to the tree with `addCollection(new RouteCollection())`. In contrast to the form component, e.g. `$form->get('child')->get('grandchild')`.
So you can see the RouteCollection cannot be used as a tree and it should not, as the same can be achieved with a flat array!
Using a flat array removes all the need for recursive traversal and makes the code much faster, much lighter, less memory (big problem in CMS with many routes) and less error-prone.
BC break: there is only a BC break if somebody used the PHP API for defining RouteCollection and also added a Route to a collection after it has been added to another collection.
So
```
$rootCollection = new RouteCollection();
$subCollection = new RouteCollection();
$rootCollection->addCollection($subCollection);
$subCollection->add('foo', new Route('/foo'));
```
must be updated to the following (otherwise the 'foo' Route is not imported to the rootCollection)
```
$rootCollection = new RouteCollection();
$subCollection = new RouteCollection();
$subCollection->add('foo', new Route('/foo'));
$rootCollection->addCollection($subCollection);
```
Also one must call addCollection from the bottom to the top. So the correct sequence is the following (and not the reverse)
```
$childCollection->->addCollection($grandchildCollection);
$rootCollection->addCollection($childCollection);
```
Remeber, this is only needed when using PHP for defining routes and calling methods in a special order. There is no change required when using XML or YAML for definitions. Also, I'm pretty sure that neither the CMF, nor Drupal routing, nor Silex is relying on the tree stuff. So they should also still work.
cc @fabpot @crell @dbu
One more thing: RouteCollection wasn't an appropriate name for a tree anyway as a collection of routes (that it now is) is definitely not a tree.
Yet another point: The XML declaration of routes uses the `<import>` element, which is excatly what the new implementation of addCollection without the need of a tree does. So this is now also more analogous.
---------------------------------------------------------------------------
by Koc at 2012-11-26T17:34:15Z
What benefit of this?
---------------------------------------------------------------------------
by Tobion at 2012-11-26T17:56:53Z
@Koc Why did you not simply wait for the description? ^^
---------------------------------------------------------------------------
by dbu at 2012-11-26T18:33:09Z
i love PR that remove more code than they add whithout removing functionality.
---------------------------------------------------------------------------
by Crell at 2012-11-26T18:49:52Z
There's an issue somewhere in Drupal where we're trying to use addCollection() as a shorthand for iterating over one collection and calling add() on the other for each item. We can't do that, however, because the subcollections are not flattened properly when reading back and our current dumper can't cope with that. So this change would not harm Drupal at all, and would mean I don't have fix a bug in our dumper. :-) I cannot speak for any other projects, of course.
---------------------------------------------------------------------------
by Tobion at 2012-11-27T19:06:34Z
Ok, this is ready.
Commits
-------
31843cf [FrameworkBundle] Add info to config
d5ab4c1 [Routing] Update changelog
bbef65e [Routing] Add strict_parameters option to disable exceptions when a route generation fails due to an invalid parameter
Discussion
----------
[Routing] Add strict_parameters option to disable exceptions on invalid parameters
---------------------------------------------------------------------------
by travisbot at 2012-06-09T15:07:26Z
This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1577025) (merged bbef65e6 into 37678e17).
---------------------------------------------------------------------------
by stof at 2012-06-09T15:43:48Z
Seems good, but you forgot to update the Changelog of the component. Anyway, let's wait for @vicb's review as he knows the Routing component better than me.
---------------------------------------------------------------------------
by Seldaek at 2012-06-09T16:35:56Z
I updated the changelog
---------------------------------------------------------------------------
by travisbot at 2012-06-09T16:38:31Z
This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1577716) (merged d5ab4c1d into 37678e17).
---------------------------------------------------------------------------
by travisbot at 2012-06-11T10:10:37Z
This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1590901) (merged a54e59e4 into 37678e17).
---------------------------------------------------------------------------
by travisbot at 2012-06-11T13:50:21Z
This pull request [passes](http://travis-ci.org/symfony/symfony/builds/1591926) (merged 31843cf0 into 0995b1f2).
