Actualización

vendor/knplabs/knp-components/doc/pager/config.md

@@ -0,0 +1,54 @@
+## Configuration
+
+
+Some subscribers will take into account some options.  
+These options can be passed as the 4th argument of `Paginator::paginate()`.
+
+For example, Doctrine ORM subscriber will generate different sql queries if the `distinct` options changes.
+
+
+The list of existing options are:
+
+| name                       | type           | default value | subscribers                                     |
+| -------------------------- | -------------- | ------------- | ----------------------------------------------- |
+| wrap-queries               | bool           | false         | orm QuerySubscriber, orm QueryBuilderSubscriber |
+| distinct                   | bool           | true          | QuerySubscriber, QueryBuilderSubscriber         |
+| pageParameterName          | string         | page          | SortableSubscriber                              |
+| defaultSortFieldName       | string\|array* |               | SortableSubscriber                              |
+| defaultSortDirection       | string         | asc           | SortableSubscriber                              |
+| sortFieldWhitelist         | array          | []            | SortableSubscriber                              |
+| sortFieldParameterName     | string         | sort          | SortableSubscriber                              |
+| sortDirectionParameterName | string         | direction     | SortableSubscriber                              |
+| defaultFilterFields        | string\|array* |               | FiltrationSubscriber                            |
+| filterFieldWhitelist       | array          |               | FiltrationSubscriber                            |
+| filterFieldParameterName   | string         | filterParam   | FiltrationSubscriber                            |
+| filterValueParameterName   | string         | filterValue   | FiltrationSubscriber                            |
+
+
+## Noticeable behaviors of some options
+
+### `distinct`
+
+If set to true, will add a distinct sql keyword on orm queries to ensuire unicity of counted results
+
+
+### `wrap-queries`
+
+If set to true, will take advantage of doctrine 2.3 output walkers by using subqueries to handle composite keys and HAVING queries.
+This can considerably impact performances depending on the query and the platform, you will have to consider it at some point.
+
+If you want to order your results by a column from a fetch joined t-many association,
+you have to set `wrap-queries` to `true`. Otherwise you will get an exception with this warning:
+*"Cannot select distinct identifiers from query with LIMIT and ORDER BY on a column from a fetch joined to-many association. Use output walkers."*
+
+
+### `defaultSortFieldName`
+
+Used as default field name for the sorting. It can take an array for sorting by multiple fields.
+
+\* **Attention**: Arrays are only supported for *Doctrine's ORM*.
+
+
+### `defaultFilterFields`
+
+Used as default field names for the filtration. It can take an array for filtering by multiple fields.

vendor/knplabs/knp-components/doc/pager/intro.md

@@ -0,0 +1,61 @@
+# Intro to Knp Pager Component
+
+This is a PHP 5.3 paginator with a totally different core concept.
+
+**Note:** it is still experimental, any ideas on structural design are very welcome
+
+How is it different? First of all, it uses Symfony's **event dispatcher** to paginate whatever is needed.
+The pagination process involves triggering events which hit the **subscribers**. If the subscriber
+knows how to paginate the given object, it does. Finally, some subscriber must initialize the
+**pagination view** object, which will be the result of pagination request. Pagination view
+can be anything which will be responsible for how to render the pagination.
+
+**Magic?** no! only KISS principle
+
+Why reinvent the wheel? Can someone tell me what's the definition of **wheel** in the software world? 
+
+## Requirements:
+
+- Symfony EventDispatcher component
+- Namespace based autoloader for this library
+
+## Features:
+
+- Can be customized in any way needed, etc.: pagination view, event subscribers.
+- Possibility to add custom filtering, sorting functionality depending on request parameters.
+- Pagination view extensions based on event.
+- Paginator extensions based on events, etc.: another object pagination compatibilities.
+- Supports multiple paginations during one request
+- Separation of concern, paginator is responsible for generating the pagination view only,
+pagination view - for representation purposes.
+- Does not require initializing specific adapters
+- [configurable](config.md)
+
+## Usage examples:
+
+### Controller
+
+```php
+$paginator = new Knp\Component\Pager\Paginator;
+$target = range('a', 'u');
+// uses event subscribers to paginate $target
+$pagination = $paginator->paginate($target, 2/*page*/, 10/*limit*/);
+
+// iterate paginated items
+foreach ($pagination as $item) {
+    //...
+}
+echo $pagination; // renders pagination
+
+// overriding view rendering
+
+$pagination->renderer = function($data) use ($template) {
+    return $twig->render($template, $data);
+};
+
+echo $pagination;
+
+// or paginate Doctrine ORM query
+
+$pagination = $paginator->paginate($em->createQuery('SELECT a FROM Entity\Article a'), 1, 10);
+```

vendor/knplabs/knp-components/doc/pager/usage.md

@@ -0,0 +1,113 @@
+# Usage of Pager component
+
+This tutorial will cover installation and usage examples.
+
+## Installation
+
+    composer require "knplabs/knp-components:~1.2"
+
+## Basic usage
+
+As mentioned in [introduction](https://github.com/knplabs/knp-components/tree/master/doc/pager/intro.md)
+paginator uses event listeners to paginate the given data. First we will start from the simplest data - array.
+Lets add some code in **index.php** and see it in action:
+
+``` php
+<?php
+// file: index.php
+include 'autoloader.php';
+
+// usage examples will continue here
+
+use Knp\Component\Pager\Paginator; // used class name
+
+// end of line and tab definition
+define('EOL', php_sapi_name() === 'cli' ? PHP_EOL : '<br/>');
+define('TAB', php_sapi_name() === 'cli' ? "\t" : '<span style="margin-left:25px"/>');
+
+$paginator = new Paginator; // initializes default event dispatcher, with standard listeners
+$target = range('a', 'z'); // an array to paginate
+// paginate target and generate representation class, it can be overrided by event listener
+$pagination = $paginator->paginate($target, 1/*page number*/, 10/*limit per page*/);
+
+echo 'total count: '.$pagination->getTotalItemCount().EOL;
+echo 'pagination items of page: '.$pagination->getCurrentPageNumber().EOL;
+// iterate items
+foreach ($pagination as $item) {
+    //...
+    echo TAB.'paginated item: '.$item.EOL;
+}
+
+$pagination = $paginator->paginate($target, 3/*page number*/, 10/*limit per page*/);
+echo 'pagination items of page: '.$pagination->getCurrentPageNumber().EOL;
+// iterate items
+foreach ($pagination as $item) {
+    //...
+    echo TAB.'paginated item: '.$item.EOL;
+}
+```
+
+### Rendering pagination
+
+**$paginator->paginate($target...)** will return pagination class, which is by
+default **SlidingPagination** it executes a **$pagination->renderer** callback
+with all arguments reguired in view template. Its your decision to implement
+it whatever way you like.
+
+**Note:** this is the default method. There will be more examples on how to render pagination templates
+
+So if you by default print the pagination you should see something like:
+
+``` php
+<?php
+// continuing in file: index.php
+// ...
+
+echo $pagination; // outputs: "override in order to render a template"
+```
+
+Now if we override the renderer callback
+
+``` php
+<?php
+// continuing in file: index.php
+// ...
+
+$pagination->renderer = function($data) {
+    return EOL.TAB.'page range: '.implode(' ', $data['pagesInRange']).EOL;
+};
+echo $pagination; // outputs: "page range: 1 2 3"
+```
+
+## Sorting database query results by multiple columns (only Doctrine ORM)
+
+It is not uncommonly that the result of a database query should be sorted by multiple columns.
+For example users should be sorted by lastname and by firstname:
+
+```php
+$query = $entityManager->createQuery('SELECT u FROM User');
+
+$pagination = $paginator->paginate($query, 1/*page number*/, 20/*limit per page*/, array(
+    'defaultSortFieldName' => array('u.lastname', 'u.firstname'),
+    'defaultSortDirection' => 'asc',
+));
+```
+
+The Paginator will add an `ORDER BY` automatically for each attribute for the
+`defaultSortFieldName` option.
+
+## Filtering database query results by multiple columns (only Doctrine ORM and Propel)
+
+You can also filter the result of a database query by multiple columns.
+For example users should be filtered by lastname or by firstname:
+
+```php
+$query = $entityManager->createQuery('SELECT u FROM User');
+
+$pagination = $paginator->paginate($query, 1/*page number*/, 20/*limit per page*/, array(
+    'defaultFilterFields' => array('u.lastname', 'u.firstname'),
+));
+```
+
+If the `filterValue` parameter is set, the Paginator will add an `WHERE` condition automatically 
+for each attribute for the `defaultFilterFields` option. The conditions are `OR`-linked.