merged branch fabpot/tokenparserbroker (PR #903)

This PR was merged into the master branch.

Commits
-------

8563e04 deprecated the token parser broker sub-system

Discussion
----------

deprecated the token parser broker sub-system

This is the first of a series of PRs where I want to deprecate some features that made sense at some point but do not anymore or features that are barely used. Deprecated features will still work in all versions of Twig 1.x but they will be removed in Twig 2.0.

This first one should not be controversial. The token parser broker was added at a time where functions in Twig were not available. Nowadays, creating a new tag is so rare that I cannot see any usage for the broker system.

As far as I know, nobody uses the broker system anyway (this feature is not even documented), except [Zwig](https://github.com/arnaud-lb/Zwig). And Zwig should probably create functions instead of tags for ZF helpers anyways.

ping @arnaud-lb

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

by arnaud-lb at 2012-11-16T17:27:02Z

IIRC the main reason for using this in Zwig was that ZF makes it hard to list helpers, and easy to get an helper by name. So the broken allows to use ZF helpers without listing them. The reason for using tags instead of functions is that many helpers in ZF are not used for their return value and/or printing. (Zwig also exposes helpers as functions, through registerUndefinedFunctionCallback, for those used for their return value or printing.)

No objection for removing in 2.x though.

doc/deprecated.rst

@@ -0,0 +1,14 @@
+Deprecated Features
+===================
+
+This document lists all deprecated features in Twig 1.x. They are kept for
+backward compatibility but they will be removed in Twig 2.0.
+
+Token Parsers
+-------------
+
+* The token parser broker sub-system is deprecated; the following class and
+  interface will be removed in 2.0:
+
+  * ``Twig_TokenParserBrokerInterface``
+  * ``Twig_TokenParserBroker``

doc/index.rst

@@ -15,3 +15,4 @@ Twig
     filters/index
     functions/index
     tests/index
+    deprecated

lib/Twig/TokenParserBroker.php

@@ -15,6 +15,8 @@
  *
  * @package twig
  * @author  Arnaud Le Blanc <arnaud.lb@gmail.com>
+ *
+ * @deprecated
  */
 class Twig_TokenParserBroker implements Twig_TokenParserBrokerInterface
 {

lib/Twig/TokenParserBrokerInterface.php

@@ -17,6 +17,8 @@
  *
  * @package twig
  * @author  Arnaud Le Blanc <arnaud.lb@gmail.com>
+ *
+ * @deprecated
  */
 interface Twig_TokenParserBrokerInterface
 {