merged branch fabpot/named-paths (PR #772)

merged branch fabpot/named-paths (PR #772)

Commits
-------

7e5acd1 fixed some possible warnings
f0d0d6d fixed typo
b7076fe added Twig_Loader_Filesystem::getNamespaces()
8f7ccd1 moved an exception
9426072 tweaked documentation
b9afa84 renamed the default filesystem namespace to __main__
c34541d changed notation of namespaced templates to @namespace/template_path
0eb4d01 added namespaced templates support in Twig_Loader_Filesystem
c24ea1b added Twig_Loader_Filesystem::prependPath()

Discussion
----------

added namespaced templates support in Twig_Loader_Filesystem

Everything is explained in the updated documentation.

Basically, it gives more flexibility when it comes to manage many templates that are not necessarily related (think frontent vs backend for instance, or templates from different Symfony bundles, ...). It is useful if, for each namespace, you need to look for templates in different directories. This implementation would probably be enough to replace the current Symfony bundle template paths, with more flexibility and less restrictions.

Feedback is more than welcome. One thing I'm not sure about is the `#` separator between the namespace and the template path. Is it the best choice? We need a character that is not used in filesystem paths, so good candidates are: `@`, `!`, `%`, `$`, `*`, `;`, `?`.

Some immediate benefits: give the same template flexibility that we have in Symfony to other frameworks using Twig like Silex. Another benefit would be the ability to share template between Symfony and other frameworks like Twig (more on a proof of concept later).

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

by alessandro1997 at 2012-07-14T16:25:42Z

This is very nice, and I think # is a great choice for the separator character. We could also use @.

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

by jjbohn at 2012-07-14T16:25:59Z

:+1: for #

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

by Symfomany at 2012-07-14T16:27:45Z

Pipe character isn't candidate?

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

by inspiran at 2012-07-14T16:32:52Z

I remember from the wetter.com talk at sf live that they actually implemented a similar functionality: allow twig templates to be defined different from the default path.   So they had something like:

{% extends "cms://Home/weather/..."  ... %}
If we could make the "cms" part a configurable setting then one could use it to point to a custom folder or even to a content provider (symfony cmf?)

Maybe that would be another approach?

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

by fabpot at 2012-07-14T16:33:21Z

The other syntax possibility is something more like we have in Symfony: `@namespace/template_path`.

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

by fabpot at 2012-07-14T16:34:37Z

@inspiran: that's another possibility: use the PHP stream notation.

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

by mvrhov at 2012-07-14T16:36:18Z

I'd also prefer uri/php streams syntax...

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

by Tobion at 2012-07-14T16:41:16Z

On Windows I can create a file with `#` in it. How does it distinguish that? I don't think we will find a single seperation character that works on all file systems, do we? And `@` (e.g. namespace@file) would be semantically strange (unless you read it from right-to-left).
So I'd also prefer uri/php stream syntax.

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

by Symfomany at 2012-07-14T16:43:17Z

@fabpot  Pointer Syntax? or greater than character?

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

by markstory at 2012-07-14T16:43:48Z

I'm in favour of the `foo://` style syntax.  It is similar to other parts of PHP, and avoids overlap with filesystem characters, and doesn't introduce new unique syntax.

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

by stof at 2012-07-14T16:44:25Z

@fabpot ``@namespace/template_path`` would make it confusing in Symfony. Because locating a resource with the kernel would use ``@AcmeDemoBundle/Resources/views/layout.html.twig`` whereas Twig would find the same file as ```@AcmeDemoBundle/layout.html.twig``.

And none of ``#``, ``@``, ``!``, ``%``, ``$`` or ``;`` is forbidden in filenames on Windows.

So I think the URI/stream notation is fine

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

by maryo at 2012-07-14T16:46:44Z

On Windows @!%$; are valid. Invalid characters are \/:*?"<>|

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

by maryo at 2012-07-14T16:47:55Z

Is > allowed on Linux?

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

by jschreuder at 2012-07-14T16:49:17Z

Some thoughts from a non-Symfony user:

* Not sure about the `#`, on the one hand it is used as the comment character on the other hand I'm also familiar with it as a membership operator (which supports its usage)
* The streams/PHP syntax: I don't really like this, the syntax signifies some type of protocol to be used. Even stretched to the limits of its definition you wouldn't be able to define different namespaces as different protocols (same protocol, different location).
* `@namespace/file/path` - kind of like this one, the `@` signifies that it is followed by a special symbol (being the namespace name) and other than that a normal path.
* Another option we've used in Fuel is the double colon `::` as in `namespace::file/path` (like the `#` it signifies membership, but doesn't have another significance in Twig)

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

by gunnarlium at 2012-07-14T17:10:15Z

Does it matter what symbols are valid in filenames? Won't the separator just be used for exploding the string into namespace and path, and thus never be used to directly access a file?

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

by alessandro1997 at 2012-07-14T17:15:27Z

As @gunnarlium said, what's the problem with filenames?

```php
$path = 'namespace#new#page.html';
$parts = explode('#', $path, 2);
list($namespace, $filename) = $parts;

// "namespace and "new#page.html"
var_dump($namespace, $filename);
```

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

by stof at 2012-07-14T17:16:19Z

@gunnarlium the issue is that if you use this symbols in the filename of your template without namespace, Twig will consider it as a namespaced template for another file name

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

by stof at 2012-07-14T17:16:45Z

@alessandro1997 the issue is that namespaces are optional

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

by alessandro1997 at 2012-07-14T17:17:07Z

@stof Oh, right. I didn't get that :-)

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

by gunnarlium at 2012-07-14T17:20:32Z

@stof Ok, I see. So what we want is a symbol which is not allowed as a filename? Or (suboptimally) just add a requirement that template filenames can't contain certain reserved symbols?

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

by fabpot at 2012-07-14T17:23:37Z

But then, who is using `#` in a filename?

Anyway, I'm going to implement a version based on PHP streams to stick to the PHP way. Using a PHP stream might also allow us to get rid of the array loader.

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

by alessandro1997 at 2012-07-14T17:24:01Z

@gunnarlium But how would we check if the user is using reserved symbols in template names? Twig isn't aware of the available templates' names until the user requests them. And when he/she does it's too late because Twig doesn't know if the separator is used as namespace or if it's part of the filename.

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

by stof at 2012-07-14T17:33:38Z

@fabpot even if no sane guy would probably use ``#`` in a filename, it would mean that Twig assumes that all its userbase is sane :)

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

by lolautruche at 2012-07-14T18:51:53Z

-1 for #
+1 for php stream, though I agree with @jschreuder's arguments against it
+2 for @ syntax like in Symfony. I find it more consistent.

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

by fabpot at 2012-07-14T19:50:31Z

One problem with PHP streams is that it makes using template names quite ugly and verbose:

    {% include 'twig://namespace/index.html' %}

And for non-namespaced templates:

    {% include 'twig:///index.html' %}

for which we can provide a shortcut:

    {% include 'index.html' %}

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

by fabpot at 2012-07-14T19:54:35Z

If we are using `@` like in Symfony, it will be:

    {% include '@namespace/index.html' %}

And for non-namespaced templates:

    {% include 'index.html' %}

And for Symfony users, the notation would be the same as for resources. If we register each bundle path as a namespace, the path would even be exactly the same:

    {% include '@AcmeDemoBundle/Resources/views/layout.html.twig' %}

EDIT: that's not so simple because of the templates stored under `app/`.

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

by mahono at 2012-07-14T19:56:54Z

might not be the best idea, but what about using Backslash as namespace char?

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

by fabpot at 2012-07-14T19:57:50Z

@mahono: I have not dared to propose this alternative ;)

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

by fabpot at 2012-07-14T20:06:17Z

I've just made an additional commit that implements the `@namespace/template_path` notation.

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

by Baachi at 2012-07-14T20:32:41Z

The `@` syntax is the most consistent solution.
But the integration in symfony2 is really hard and a BC break.

The stream syntax is not a good solution.
`twig` might already be already registered as a stream.

I would suggest the `::` syntax.