This is because some templates, e.g. errror, expect to be able to
include them. This fixes e.g. the No State error page.

*    Updated the phpDoc comments to match the code
*    Added return statements
*    Added return values

This seemed the logical place to do it, because it's essentially
a presentation thing (so in Template, not Locale). There's likely
something to be said for sorting by key aswell as sorting by
translated language name. Picked key for now, seems most predictable.

setupTwigTemplatepaths() cannot return false

This seemed the logical place to do it, because it's essentially
a presentation thing (so in Template, not Locale). There's likely
something to be said for sorting by key aswell as sorting by
translated language name. Picked key for now, seems most predictable.

This allows us to load templates from modules inside a twig template itself (include, embed, etc), even when the main template is not in a module or in a different one.

This can be used by templates to load resources in different ways, either optimized for the developer or for a production environment.

This allows us to use this new filter to translate strings from a given array of translations, where every translation is indexed by its ISO 639 code. A new configuration option ('language' -> 'priorities') is available too to control the alternative languages that can be used instead of a given language, when the latter is not found. The filter returns null when no suitable translation is found, so that it can be combined with "default()" to set a default translation for a given string.

This resolves #695.

Otherwise, a theme would not be able to include/embed/extend its own templates.

This new interface allows themes to define a class that can be hooked at certain specific points of template initialization/handling, so that they can do stuff like automatically adding variables for all templates, or adding twig extensions. This classes must implement the new TemplateControllerInterface, and be specified in the "theme.controller" configuration option. This way, we avoid the performance hit if we use traditional hooks, and we also avoid hooks from other modules causing trouble.

For now, the interface offers two entry points: setUpTwig(), which allows managing the twig environment after initialization (e.g. to add an extension or define filters); and display(), which offers all the data passed to the template, and allows adding or modifying it.

This makes sense as those should be static values available to every template.

Additionally, add a "templateId" variable that we can use for templates to identify themselves.

Make sure if we are using a theme, its module is added as a valid domain where we can look for translations.

It has also an impact in performance, and covers an unlikely scenario. Instead, if you plan to use templates from another module, now you need to call the "addTemplatesFromModule()" method right after creating the template. That way you can register manually what templates you are supposed to use, being much more efficient.

An alternative way to inject data in the templates should be used. This has a terrible impact in performance, and could have undesired side effects.

This allows template users to use their own twig extensions if they want, while also allowing us to remove the "twigInit" hook. Hooks come at a price, and it doesn't make much sense to use them in this case, as they would only be useful if a module wants to add a twig extension even if the code instantiating SimpleSAML_XHTML_Template does not belong to that module. This could lead to unexpected behaviour (i.e. a module adding a hook that creates trouble for the templates defined in another module), so given the lack of use cases supporting the hook and the possible negative consequences implied, it's better to remove it.

This way we we allow those writing themes to use twig extensions, filters, or anything they may need.

This allows custom themes to inject data for all templates by simply adding a new hook.