Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/whiteoctober/Pagerfanta
Pagination for PHP.
https://github.com/whiteoctober/Pagerfanta
pagerfanta php
Last synced: 2 days ago
JSON representation
Pagination for PHP.
- Host: GitHub
- URL: https://github.com/whiteoctober/Pagerfanta
- Owner: whiteoctober
- License: other
- Fork: true (BabDev/Pagerfanta)
- Created: 2011-04-26T18:55:28.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2020-06-09T11:57:17.000Z (over 4 years ago)
- Last Synced: 2024-08-01T21:59:17.454Z (3 months ago)
- Topics: pagerfanta, php
- Language: PHP
- Homepage:
- Size: 361 KB
- Stars: 1,595
- Watchers: 40
- Forks: 2
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: code_of_conduct.md
Awesome Lists containing this project
- awesome-php - Pagerfanta - A pagination library. (Configuration / Miscellaneous)
- awesome-php-cn - Pagerfanta - 一个分页库. (配置 Configuration / 杂项 Miscellaneous)
- awesome-projects - Pagerfanta - A pagination library. (Configuration / Miscellaneous)
- awesome-php - Pagerfanta - A pagination library. (Configuration / Miscellaneous)
README
**NB** This project is no longer maintained; you may like to use https://github.com/BabDev/Pagerfanta instead.
# Pagerfanta
[](https://travis-ci.org/whiteoctober/Pagerfanta) [](https://scrutinizer-ci.com/g/whiteoctober/Pagerfanta/) [](https://scrutinizer-ci.com/g/whiteoctober/Pagerfanta/) [](https://insight.sensiolabs.com/projects/9e710230-b088-4904-baef-5f5e2d62e681) [](https://packagist.org/packages/pagerfanta/pagerfanta) [](https://packagist.org/packages/pagerfanta/pagerfanta)
This project is for PHP 7.
If you need support for PHP < 7, use [Release v1.1.0](https://github.com/whiteoctober/Pagerfanta/releases/tag/v1.1.0).
## Usage
```php
setMaxPerPage($maxPerPage); // 10 by default
$maxPerPage = $pagerfanta->getMaxPerPage();
$pagerfanta->setCurrentPage($currentPage); // 1 by default
$currentPage = $pagerfanta->getCurrentPage();
$nbResults = $pagerfanta->getNbResults();
$currentPageResults = $pagerfanta->getCurrentPageResults();
```
Some of the other methods available:
```php
$pagerfanta->getNbPages();
$pagerfanta->haveToPaginate(); // whether the number of results is higher than the max per page
$pagerfanta->hasPreviousPage();
$pagerfanta->getPreviousPage();
$pagerfanta->hasNextPage();
$pagerfanta->getNextPage();
$pagerfanta->getCurrentPageOffsetStart();
$pagerfanta->getCurrentPageOffsetEnd();
```
### Changing the page based on user selection
If you're using the example route-generator function shown below,
the page selected by the user will be available in the `page` GET (querystring) parameter.
You would then need to call `setCurrentPage` with the value of that parameter:
```php
if (isset($_GET["page"])) {
$pagerfanta->setCurrentPage($_GET["page"]);
}
```
### setMaxPerPage and setCurrentPage
The `->setMaxPerPage()` and `->setCurrentPage()` methods implement
a fluent interface:
```php
setMaxPerPage($maxPerPage)
->setCurrentPage($currentPage);
```
The `->setMaxPerPage()` method throws an exception if the max per page
is not valid:
* `Pagerfanta\Exception\NotIntegerMaxPerPageException`
* `Pagerfanta\Exception\LessThan1MaxPerPageException`
Both extend from `Pagerfanta\Exception\NotValidMaxPerPageException`.
The `->setCurrentPage()` method throws an exception if the page is not valid:
* `Pagerfanta\Exception\NotIntegerCurrentPageException`
* `Pagerfanta\Exception\LessThan1CurrentPageException`
* `Pagerfanta\Exception\OutOfRangeCurrentPageException`
All of them extend from `Pagerfanta\Exception\NotValidCurrentPageException`.
`->setCurrentPage()` throws an out ot range exception depending on the
max per page, so if you are going to modify the max per page, you should do it
before setting the current page.
(If you want to use Pagerfanta in a Symfony project, see
[https://github.com/whiteoctober/WhiteOctoberPagerfantaBundle](https://github.com/whiteoctober/WhiteOctoberPagerfantaBundle).)
## Adapters
The adapter's concept is very simple. An adapter just returns the number
of results and an slice for a offset and length. This way you can adapt
a pagerfanta to paginate any kind results simply by creating an adapter.
An adapter must implement the `Pagerfanta\Adapter\AdapterInterface`
interface, which has these two methods:
```php
find();
$adapter = new MongoAdapter($cursor);
```
### MandangoAdapter
To paginate [Mandango](http://mandango.org) Queries.
```php
getRepository('Model\Article')->createQuery();
$adapter = new MandangoAdapter($query);
```
### DoctrineDbalAdapter
To paginate [DoctrineDbal](http://www.doctrine-project.org/projects/dbal.html)
query builders.
```php
select('p.*')->from('posts', 'p');
$countQueryBuilderModifier = function ($queryBuilder) {
$queryBuilder->select('COUNT(DISTINCT p.id) AS total_results')
->setMaxResults(1);
};
$adapter = new DoctrineDbalAdapter($queryBuilder, $countQueryBuilderModifier);
```
### DoctrineDbalSingleTableAdapter
To simplify the pagination of single table
[DoctrineDbal](http://www.doctrine-project.org/projects/dbal.html)
query builders.
This adapter only paginates single table query builders, without joins.
```php
select('p.*')->from('posts', 'p');
$countField = 'p.id';
$adapter = new DoctrineDbalSingleTableAdapter($queryBuilder, $countField);
```
### DoctrineORMAdapter
To paginate [DoctrineORM](http://www.doctrine-project.org/projects/orm) query objects.
```php
createQueryBuilder()
->select('u')
->from('Model\Article', 'u');
$adapter = new DoctrineORMAdapter($queryBuilder);
```
### DoctrineODMMongoDBAdapter
To paginate [DoctrineODMMongoDB](http://www.doctrine-project.org/docs/mongodb_odm/1.0/en/) query builders.
```php
createQueryBuilder('Model\Article');
$adapter = new DoctrineODMMongoDBAdapter($queryBuilder);
```
### DoctrineODMPhpcrAdapter
To paginate [Doctrine PHPCR-ODM](http://docs.doctrine-project.org/projects/doctrine-phpcr-odm/en/latest/) query builders.
```php
createQueryBuilder();
$queryBuilder->from('Model\Article');
$adapter = new DoctrineODMPhpcrAdapter($queryBuilder);
```
### DoctrineCollectionAdapter
To paginate a `Doctrine\Common\Collection\Collections` interface
you can use the `DoctrineCollectionAdapter`. It proxies to the
count() and slice() methods on the Collections interface for
pagination. This makes sense if you are using Doctrine ORMs Extra
Lazy association features:
```php
find("Pagerfanta\Tests\Adapter\DoctrineORM\User", 1);
$adapter = new DoctrineCollectionAdapter($user->getGroups());
```
### DoctrineSelectableAdapter
To paginate a `Doctrine\Common\Collection\Selectable` interface
you can use the `DoctrineSelectableAdapter`. It uses the matching()
method on the Selectable interface for pagination. This is
especially usefull when using the Doctrine Criteria object to
filter a PersistentCollection:
```php
find("Pagerfanta\Tests\Adapter\DoctrineORM\User", 1);
$comments = $user->getComments();
$criteria = Criteria::create()->andWhere(Criteria::expr()->in('id', array(1,2,3));
$adapter = new DoctrineSelectableAdapter($comments, $criteria);
```
Note that you should never use this adapter with a
PersistentCollection which is not set to use the EXTRA_LAZY fetch mode.
*Be careful when using the `count()` method, currently Doctrine2
needs to fetch all the records to count the number of elements.*
### ElasticaAdapter
To paginate an Elastica Query query:
```php
'Fred'
));
$adapter = new ElasticaAdapter($searchable, $query);
```
*Be careful when paginating a huge set of documents. By default, offset + limit
can't exceed 10000. You can mitigate this by setting the `$maxResults`
parameter when constructing the `ElasticaAdapter`. For more information, see:
[#213](https://github.com/whiteoctober/Pagerfanta/pull/213#issue-87631892).*
### PropelAdapter
To paginate a propel 1 query:
```php
createSelect();
$query->setQuery('search term');
$adapter = new SolariumAdapter($solarium, $query);
```
### FixedAdapter
Best used when you need to do a custom paging solution and
don't want to implement a full adapter for a one-off use case.
It returns always the same data no matter what page you query:
```php
3);
$html = $view->render($pagerfanta, $routeGenerator, $options);
```
Options (default):
* proximity (3)
* prev_message (Previous)
* next_message (Next)
* css_disabled_class (disabled)
* css_dots_class (dots)
* css_current_class (current)
* dots_text (...)
* container_template (%pages%)
* page_template (%text%)
* span_template (%text%)
CSS:
```css
.pagerfanta {
}
.pagerfanta a,
.pagerfanta span {
display: inline-block;
border: 1px solid blue;
color: blue;
margin-right: .2em;
padding: .25em .35em;
}
.pagerfanta a {
text-decoration: none;
}
.pagerfanta a:hover {
background: #ccf;
}
.pagerfanta .dots {
border-width: 0;
}
.pagerfanta .current {
background: #ccf;
font-weight: bold;
}
.pagerfanta .disabled {
border-color: #ccf;
color: #ccf;
}
COLORS:
.pagerfanta a,
.pagerfanta span {
border-color: blue;
color: blue;
}
.pagerfanta a:hover {
background: #ccf;
}
.pagerfanta .current {
background: #ccf;
}
.pagerfanta .disabled {
border-color: #ccf;
color: #cf;
}
```
### TwitterBootstrapView, TwitterBootstrap3View and TwitterBootstrap4View
These views generate paginators designed for use with
[Twitter Bootstrap](https://github.com/twitter/bootstrap).
`TwitterBootstrapView` is for Bootstrap 2; `TwitterBootstrap3View` is for Bootstrap 3; `TwitterBootstrap4View` is for Bootstrap 4 (alpha).
```php
3);
$html = $view->render($pagerfanta, $routeGenerator, $options);
```
Options (default):
* proximity (3)
* prev_message (← Previous)
* prev_disabled_href ()
* next_message (Next →)
* next_disabled_href ()
* dots_message (…)
* dots_href ()
* css_container_class (pagination)
* css_prev_class (prev)
* css_next_class (next)
* css_disabled_class (disabled)
* css_dots_class (disabled)
* css_active_class (active)
### SemanticUiView
This view generates a pagination for
[Semantic UI](https://github.com/Semantic-Org/Semantic-UI).
```php
3);
$html = $view->render($pagerfanta, $routeGenerator, $options);
```
Options (default):
* proximity (3)
* prev_message (← Previous)
* prev_disabled_href ()
* next_message (Next →)
* next_disabled_href ()
* dots_message (…)
* dots_href ()
* css_container_class (pagination)
* css_item_class (item)
* css_prev_class (prev)
* css_next_class (next)
* css_disabled_class (disabled)
* css_dots_class (disabled)
* css_active_class (active)
### OptionableView
This view is to reuse options in different views.
```php
3));
$myView2 = new OptionableView($defaultView, array('prev_message' => 'Anterior', 'next_message' => 'Siguiente'));
// using in a normal way
$pagerfantaHtml = $myView2->render($pagerfanta, $routeGenerator);
// overwriting default options
$pagerfantaHtml = $myView2->render($pagerfanta, $routeGenerator, array('next_message' => 'Siguiente!!'));
```
## Contributing
We welcome contributions to this project, including pull requests and issues (and discussions on existing issues).
If you'd like to contribute code but aren't sure what, the [issues list](https://github.com/whiteoctober/pagerfanta/issues) is a good place to start.
If you're a first-time code contributor, you may find Github's guide to [forking projects](https://guides.github.com/activities/forking/) helpful.
All contributors (whether contributing code, involved in issue discussions, or involved in any other way) must abide by our [code of conduct](code_of_conduct.md).
## Acknowledgements
Pagerfanta is inspired by [Zend Paginator](https://github.com/zendframework/zf2).
Thanks also to Pablo Díez ([email protected]) for most of the work on the first versions of Pagerfanta.
## Licence
Pagerfanta is licensed under the [MIT License](LICENSE).