Updated the doc and the changelog

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## 2.0 (2012-XX-XX)
 
+* [BC break] Refactored the way to mark items as current
 * [BC break] Changed the format of the breadcrumb array
   Instead of storing the elements with the label as key and the uri as value
   the array now stores an array of array elements with 3 keys: `label`, `uri` and `item`.

doc/01-Basic-Menus.markdown

@@ -21,6 +21,7 @@ For example:
 ```php
 <?php
 
+use Knp\Menu\Matcher\Matcher;
 use Knp\Menu\MenuFactory;
 use Knp\Menu\Renderer\ListRenderer;
 
@@ -30,7 +31,7 @@ $menu->addChild('Home', array('uri' => '/'));
 $menu->addChild('Comments', array('uri' => '#comments'));
 $menu->addChild('Symfony2', array('uri' => 'http://symfony-reloaded.org/'));
 
-$renderer = new ListRenderer();
+$renderer = new ListRenderer(new Matcher());
 echo $renderer->render($menu);
 ```
 
@@ -67,7 +68,7 @@ be turned off by passing the `true` as the second argument to the renderer.
 
 // ...
 
-$renderer = new ListRenderer(null, true);
+$renderer = new ListRenderer(new Matcher(), array('compressed' => true));
 echo $renderer->render($menu);
 ```
 
@@ -79,7 +80,7 @@ You can also compress (or not compress) on a menu-by-menu basis by using the
 
 // ...
 
-$renderer = new ListRenderer();
+$renderer = new ListRenderer(new Matcher());
 echo $renderer->render($menu, array('compressed' => true));
 ```
 
@@ -93,7 +94,6 @@ it implements ArrayAccess, Countable and Iterator:
 <?php
 
 use Knp\Menu\MenuFactory;
-use Knp\Menu\Renderer\ListRenderer;
 
 $factory = new MenuFactory();
 $menu = $factory->createItem('My menu');
@@ -237,6 +237,7 @@ the second argument to the `render()` method:
 * `lastClass` (default:  `last`)
 * `compressed` (default: `false`)
 * `allow_safe_labels` (default: `false`)
+* `clear_matcher` (default `true`): whether to clear the internal cache of the matcher after rendering
 
 >**NOTE**
 >When setting the `allow_safe_labels` option to `true`, you can specify that
@@ -247,47 +248,47 @@ the second argument to the `render()` method:
 The Current Menu Item
 ---------------------
 
-If the URI of a menu item matches the current URL, a `current` class will
-be added to the `li` around that item, as well as a `current_ancestor` around
-any of its parent `li` elements.
-
-But this is not done magically. In order for this to work, you must set the
-current URI on the root menu item:
+If the menu item is matched as current, a `current` class will be added to
+the `li` around that item, as well as a `current_ancestor` around any of
+its parent `li` elements. This state can either be forced on the item by
+setting it explicitly or matched using several voters.
 
 ```php
 <?php
 
+use Knp\Menu\Matcher\Matcher;
+use Knp\Menu\Matcher\Voter\UriVoter;
 use Knp\Menu\MenuFactory;
 use Knp\Menu\Renderer\ListRenderer;
 
 $factory = new MenuFactory();
 $menu = $factory->createItem('My menu');
 
-// set the current URL
-$menu->setCurrentUri('/my_comments');
-// $menu->setCurrentUri($_REQUEST['PATH_INFO]);
+// set the current state explicitly
+$menu['current_item']->setCurrent(true);
+$menu['non_current_item']->setCurrent(false);
 
-// ...
-```
+// Use the voter
+$menu['other_item']->setCurrent(null); // default value for items
 
-Alternatively, you can manually set which menu item should be marked as current,
-independent of the current URL:
+$matcher = new Matcher();
+$matcher->addVoter(new UriVoter($_SERVER['REQUEST_URI']));
 
-```php
-<?php
-// ...
+$renderer = new ListRenderer($matcher);
+```
 
-$menu['Comments']->setCurrent(true);
+The library provides 2 implementations of the VoterInterface:
 
-// ...
-```
+ * `Knp\Menu\Matcher\Voter\UriVoter` matching against the uri of the item
+ * `Knp\Menu\Silex\Voter\RouteVoter` matching the `_route` attribute of a
+   Symfony Request object against the `routes` extra of the item
 
 Creating a Menu from a Tree structure
 -------------------------------------
 
 You can create a menu easily from a Tree structure (a nested set for example) by
-making it implement ``Knp\Menu\NodeInterface``. You will then be able
-to create the menu easily (assuming ``$node`` is the root node of your structure):
+making it implement `Knp\Menu\NodeInterface`. You will then be able
+to create the menu easily (assuming `$node` is the root node of your structure):
 
 ```php
 <?php

doc/02-Twig-Integration.markdown

@@ -24,9 +24,10 @@ $twigLoader = new \Twig_Loader_Filesystem(array(
 ));
 $twig = new \Twig_Environment($twigLoader);
 
+$itemMatcher = \Knp\Menu\Matcher\Matcher();
 // setup some renderer
-$renderer = new \Knp\Menu\Renderer\ListRenderer();
-//$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig');
+$renderer = new \Knp\Menu\Renderer\ListRenderer($itemMatcher);
+//$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig', $itemMatcher);
 
 // render a template
 $template = $twig->loadTemplate('menu.twig');
@@ -62,8 +63,9 @@ so that your renderers can be lazy-loaded.
 <?php
 // setup pimple, and assign the renderer to "menu_renderer"
 $pimple = new \Pimple();
+$itemMatcher = \Knp\Menu\Matcher\Matcher();
 $pimple['list_renderer'] = function() {
-    return new \Knp\Menu\Renderer\ListRenderer();
+    return new \Knp\Menu\Renderer\ListRenderer($itemMatcher);
 };
 
 $rendererProvider = new \Knp\Menu\Renderer\PimpleProvider(
@@ -225,7 +227,8 @@ $twigLoader = new \Twig_Loader_Filesystem(array(
     // your own paths
 ));
 $twig = new \Twig_Environment($twigLoader);
-$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig');
+$itemMatcher = \Knp\Menu\Matcher\Matcher();
+$menuRenderer = new \Knp\Menu\Renderer\TwigRenderer($twig, 'knp_menu.html.twig', $itemMatcher);
 ```
 
 This works just like any other renderer, and will output an un-ordered list

doc/03-Silex-Integration.markdown

@@ -63,7 +63,6 @@ create the menu as a service in the application and register it in the parameter
 
 $app['my_main_menu'] = function($app) {
     $menu = $app['knp_menu.factory']->createItem('root');
-    $menu->setCurrentUri($app['request']->getRequestUri());
 
     $menu->addChild('Home', array('route' => 'homepage'));
     // ... add more children

doc/04-Iterators.md

@@ -103,8 +103,10 @@ It is a filter iterator applied on another iterator.
 $root = /* get your root item from somewhere */;
 $menu = $root['B'];
 
+$itemMatcher = \Knp\Menu\Matcher\Matcher();
+
 // create the iterator
-$iterator = new \Knp\Menu\Iterator\CurrentItemFilterIterator($menu->getIterator());
+$iterator = new \Knp\Menu\Iterator\CurrentItemFilterIterator($menu->getIterator(), $itemMatcher);
 
 foreach ($iterator as $item) {
     echo $item->getName() . " ";
@@ -121,14 +123,16 @@ filter on the previous recursive iterator:
 
 $menu = /* get your root item from somewhere */;
 
+$itemMatcher = \Knp\Menu\Matcher\Matcher();
+
 $treeIterator = new \RecursiveIteratorIterator(
     new \Knp\Menu\Iterator\RecursiveItemIterator(
         new \ArrayIterator(array($menu))
     ),
     \RecursiveIteratorIterator::SELF_FIRST
 );
 
-$iterator = new \Knp\Menu\Iterator\CurrentItemFilterIterator($treeIterator);
+$iterator = new \Knp\Menu\Iterator\CurrentItemFilterIterator($treeIterator, $itemMatcher);
 
 foreach ($iterator as $item) {
     echo $item->getName() . " ";