diff --git a/README.md b/README.md index 5eda4e2..dd0578d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,18 @@ -# Rekapager - Rekapager is a pagination library for PHP, supporting both offset-based and -keyset-based pagination. - -Full documentation is available at [rekalogika.dev/rekapager](https://rekalogika.dev/rekapager) +keyset-based pagination (also called cursor-based pagination). -## Keyset Pagination +## Keyset Pagination (or Cursor-Based Pagination) Keyset pagination is a method of pagination that uses the last row of the -current page as an anchor for the next page. This method is more efficient than -offset pagination because it leverages the index, and does not require the -database to scan all rows from the beginning to reach the desired page. +current page as an anchor for the next page. This method has these advantages +compared to the traditional offset-based pagination: + +* It is more efficient because it leverages the index. It does not require the + database to scan all rows from the beginning to reach the desired page. +* It is more resilient to data changes. The data will not drift when rows are + inserted or deleted. + +### Identifying Pages Instead of using page numbers, a page identifier object is used to reference a page. This identifier is encoded into a string and passed as a single query @@ -19,16 +21,23 @@ parameter. Because it requires only a single query parameter, it works similarly on the surface with offset pagination. Migrating from offset pagination to keyset pagination will be straightforward. The difference is that instead of having -page numbers in the URL, we'll be getting an 'ugly' string. +page numbers in the URL, we'll be getting an 'ugly' identifier, which is opaque +to the user, but meaningful to the application. It also easily allows us to keep the pagination job separate from the filtering and sorting logic. The library does not require a specific way to filter or sort your data. +### Queries + +This library supports queries with multiple sort columns. + The required query for performing keyset pagination is complex, especially if more than one column is used for sorting. This library handles that task automatically. The only requirement is that the query needs to have a -deterministic sort order. Queries with multiple sort columns are supported. +deterministic sort order. + +### Bidirectional Navigation and Page Skipping Bidirectional navigation is supported. The user will be able to navigate forward and backward from the current page. It also supports offset seeking, allowing @@ -41,11 +50,15 @@ In the user interface, the pager will look like a regular pagination control: The page number is informational only, and carried over from the start page. +### Jumping to the Last Page + Seeking to the last page is possible. And with keyset pagination, it will be as fast as seeking to the first page: ![last page](https://rekalogika.dev/rekapager/last-without-count.png) +### Page Numbers and Counting + Negative page numbers shown above indicate the page numbers from the end. The last page is -1, the second to last is -2, and so on. It is done this way because by default the pager does not fetch the total count from the underlying @@ -75,13 +88,18 @@ is not allowed to navigate to it: ![page limit](https://rekalogika.dev/rekapager/limit.png) -This feature prevents denials of service, either maliciously or accidentally. In -most cases, a real user won't have a good reason for accessing page 56267264, -but doing so can cause a denial of service to the web server, application, and -the database. +### Secure by Default + +By not counting by default, and limiting pages in offset pagination, the library +is secure by default. It prevents denials of service, either maliciously or +accidentally. In most cases, a real user won't have a good reason for accessing +page 56267264, but doing so can cause a denial of service to the web server, +application, and the database. -For interoperability, the library supports using any of the existing Pagerfanta -adapters, as well as adapting a Pagerfanta instance into an +### Pagerfanta Interoperability + +For interoperability, the library supports offset pagination using any of the +existing Pagerfanta adapters, as well as adapting a Pagerfanta instance into an `OffsetPageableInterface` instance. ## Supported Underlying Data Types @@ -107,8 +125,8 @@ use Rekalogika\Rekapager\Keyset\KeysetPageable; /** @var EntityRepository $postRepository */ $queryBuilder = $postRepository ->createQueryBuilder('p') - ->where('p.setName = :setName') - ->setParameter('setName', $setName) + ->where('p.group = :group') + ->setParameter('group', $group) ->addOrderBy('p.date', 'DESC') ->addOrderBy('p.title', 'ASC') ->addOrderBy('p.id', 'ASC'); @@ -175,20 +193,24 @@ integration provided by `rekalogika/rekapager-bundle`. {# Outputs the item from the current page #} - - - - - - - {% for post in pager.currentPage %} + - - - - + + + + - {% endfor %} + + + {% for post in pager.currentPage %} + + + + + + + {% endfor %} +
IDTitleDateContent
{{ post.id }}{{ post.title }}{{ post.date|date('Y-m-d') }}{{ post.content }}IDTitleDateContent
{{ post.id }}{{ post.title }}{{ post.date|date('Y-m-d') }}{{ post.content }}
{# Render the pager #} @@ -196,7 +218,7 @@ integration provided by `rekalogika/rekapager-bundle`. {{ rekapager(pager) }} ``` -### Batch Processing +## Batch Processing A `PageableInterface` object can also be used for batch processing a large amount of underlying data. The example below demonstrates how to do batch @@ -237,10 +259,6 @@ Then access the demo at [http://localhost:8187](http://localhost:8187). * [PagerWave](https://gitlab.com/pagerwave/PagerWave) * [fast-doctrine-paginator](https://github.com/mentionapp/fast-doctrine-paginator) -## Documentation - -[rekalogika.dev/rekapager](https://rekalogika.dev/rekapager) - ## License MIT