Skip to content
This repository has been archived by the owner on Jun 15, 2024. It is now read-only.

Commit

Permalink
Update documentation (#9)
Browse files Browse the repository at this point in the history 
* Update documentation

* Update documentation

* Fix limit

* Fix model doc

* Bump dependencies

* Fix cursors
  • Loading branch information
@chitoku-k
chitoku-k authored Jan 5, 2020
1 parent 22dd737 commit 99b8fde
Show file tree
Hide file tree
Showing 2 changed files with 211 additions and 58 deletions.
265 changes: 209 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ Rapid pagination without using OFFSET

- PHP: ^5.6 || ^7.0
- CakePHP: ^2.10
- [lampager/lampager](https://github.com/lampager/lampager): ^0.4
- [lampager/lampager][]: ^0.4

Note: [lampager/lampager-cakephp][] for CakePHP 3.x is available!

## Installing

Expand All @@ -27,7 +29,7 @@ Move `Plugin/Lampager` to the appropriate directory if necessary.

## Basic Usage

Load as a plugin. See [How To Install Plugins - 2.x](https://book.cakephp.org/2.0/en/plugins/how-to-install-plugins.html) for detail.
Load as a plugin. See [How To Install Plugins][] for detail.

Plugin needs to be loaded manually in `app/Config/bootstrap.php`:

Expand All @@ -48,20 +50,207 @@ class AppModel extends Model
}
```

Use in one or more of the following methods:

- Use in Controller (via `LampagerBehavior`)
- Use in Model (via `LampagerBehavior`)

### Use in Controller

At first, your `Model` class must have `'Lampager.Lampager'` enabled.
At first, your `Model` class must have `'Lampager.Lampager'` enabled. Use in a
way described in the Cookbook: [Pagination][]. Note the options that are
specific to Lampager such as `forward`, `seekable`, or `cursor`.

```php
$posts = $this->paginate(Post::class, [
// Lampager options
'forward' => true,
'seekable' => true,
'cursor' => [
'Post' => [
'id' => '4',
'created' => '2017-01-01 10:00:00',
],
],

// PaginatorComponent::settings query
'conditions' => [
'Post.type' => 'public',
],
'order' => [
'Post.created' => 'DESC',
'Post.id' => 'DESC',
],
'limit' => 10,
]);

$this->set('posts', $posts);
```

### Use in Model

At first, your `Model` class must have `'Lampager.Lampager'` enabled. Simply use
`Model::find` with `lampager`. The custom find type `lampager` (see
[Retrieving Your Data][]) works in a way similar to the core find type `all`
with additional parameters and post processor enabled.

```php
/** @var \Lampager\PaginationResult $posts */
$posts = $this->find('lampager', [
// Lampager options
'forward' => true,
'seekable' => true,
'cursor' => [
'Post' => [
'id' => '4',
'created' => '2017-01-01 10:00:00',
],
],

// Model::find query
'limit' => 10,
'order' => [
'Post.modified' => 'DESC',
'Post.created' => 'DESC',
'Post.id' => 'DESC',
],
]);

foreach ($posts as $post) {
/** @var mixed[][] $post */
debug($post['Post']['id']);
debug($post['Post']['created']);
debug($post['Post']['modified']);
}
```

## Classes

See also: [lampager/lampager][].

| Name | Type | Extends | Description |
|:-------------------------|:------|:------------------------------|:------------------------------------------------------------------------------------|
| `LampagerBehavior` | Class | ModelBehavior | CakePHP behavior which handles `Model::find()` and `PaginatorComponent::paginate()` |
| `LampagerArrayCursor` | Class | Lampager\\Contracts\\`Cursor` | Multi-dimensional array cursor |
| `LampagerPaginator` | Class | Lampager\\`Paginator` | Paginator implementation for CakePHP |
| `LampagerArrayProcessor` | Class | Lampager\\`ArrayProcessor` | Processor implementation for CakePHP |
| `LampagerColumnAccess` | Class | | Multi-dimensional array accessor |
| `LampagerTransformer` | Class | | CakePHP query genenrator |

## API

See also: [lampager/lampager][].

Using `Model::find()` or `PaginatorComponent::paginate()` is recommended. The
query is merged with CakePHP query and passed to `Lampager\Query`.

### LampagerPaginator::\_\_construct()<br>LampagerPaginator::create()

Create a new paginator instance. These methods are not intended to be directly
used in your code.

```php
static LampagerPaginator::create(Model $builder, array $options): static
LampagerPaginator::__construct(Model $builder, array $options)
```

Accept cursor parameters from a request and pass it through `PaginatorComponent::settings`.
### LampagerPaginator::transform()

Transform a Lampager query into a CakePHP query.

```php
LampagerPaginator::transform(\Lampager\Query $query): array
```

### LampagerPaginator::build()

Perform configure + transform.

```php
LampagerPaginator::build(array $cursor = []): array
```

### LampagerPaginator::paginate()

Perform configure + transform + process.

```php
LampagerPaginator::paginate(array $cursor = []): \Lampager\PaginationResult
```

#### Arguments

- **`(array)`** __*$cursor*__<br> An associative array that contains `$column => $value`. It must be **all-or-nothing**.
- For the initial page, omit this parameter or pass an empty array.
- For the subsequent pages, pass all the parameters. The partial one is not allowed.

#### Return Value

e.g.,

(Default format when using `Model::find()`)

```php
object(Lampager\PaginationResult)#1 (5) {
["records"]=>
array(3) {
[0]=>
array(1) {
["Post"]=>
array(3) { ... }
}
[1]=>
array(1) {
["Post"]=>
array(3) { ... }
}
[2]=>
array(1) {
["Post"]=>
array(3) { ... }
}
}
["hasPrevious"]=>
bool(false)
["previousCursor"]=>
NULL
["hasNext"]=>
bool(true)
["nextCursor"]=>
array(1) {
["Post"]=>
array(2) {
["id"]=>
string(1) "3"
["created"]=>
string(19) "2017-01-01 10:00:00"
}
}
}
```

### LampagerTransformer::\_\_construct()

Create a new transformer instance. This class is not intended to be directly
used in your code.

```php
LampagerTransformer::__construct(Model $builder, array $options)
```

## Examples

This section describes the practial usages of lampager-cakephp2.

### Use in Controller

The example below shows how to accept a cursor parameter from a request and
pass it through `PaginatorComponent::settings`. Be sure that your `Model` class
has `'Lampager.Lampager'` enabled.

```php
class PostsController extends AppController
{
// Load default PaginatorComponent of CakePHP
public $components = [
'Paginator',
];

public function index()
{
// Get cursor parameters
Expand All @@ -83,7 +272,7 @@ class PostsController extends AppController
'Post.created' => 'DESC',
'Post.id' => 'DESC',
],
'limit' => 15,
'limit' => 10,
];

/** @var mixed[][] */
Expand Down Expand Up @@ -115,54 +304,18 @@ if ($posts->hasNext) {
}
```

### Use in Model
## Supported database engines

At first, your `Model` class must have `'Lampager.Lampager'` enabled.
### MySQL, MariaDB, PostgreSQL, and SQLite

Simply use `Model::find` with `lampager`.
Supported!

```php
class Post extends AppModel
{
/**
* @return Lampager\PaginationResult
*/
public function latest(array $cursor = [])
{
return $this->find('lampager', [
// Lampager options
'forward' => true,
'seekable' => true,
'cursor' => $cursor,

// Model::find query
'limit' => 10,
'order' => [
'Post.modified' => 'DESC',
'Post.created' => 'DESC',
'Post.id' => 'DESC',
],
]);
}
}
```

## Classes

See also: [lampager/lampager](https://github.com/lampager/lampager).
### Microsoft SQL Server

| Name | Type | Extends | Description |
|:-------------------------|:------|:------------------------------|:------------------------------------------------------------------------------------|
| `LampagerBehavior` | Class | ModelBehavior | CakePHP behavior which handles `Model::find()` and `PaginatorComponent::paginate()` |
| `LampagerArrayCursor` | Class | Lampager\\Contracts\\`Cursor` | Multi-dimensional array cursor |
| `LampagerColumnAccess` | Class | | Multi-dimensional array accessor |
| `LampagerTransformer` | Class | | CakePHP query genenrator |
| `LampagerArrayProcessor` | Class | Lampager\\`ArrayProcessor` | Processor implementation for CakePHP |
| `LampagerPaginator` | Class | Lampager\\`Paginator` | Paginator implementation for CakePHP |

## API
Not supported.

See also: [lampager/lampager](https://github.com/lampager/lampager).

Using `Model::find()` or `PaginatorComponent::paginate()` is recommended. The
query is merged with CakePHP query and passed to `Lampager\Query`.
[lampager/lampager]: https://github.com/lampager/lampager
[lampager/lampager-cakephp]: https://github.com/lampager/lampager-cakephp
[How To Install Plugins]: https://book.cakephp.org/2/en/plugins/how-to-install-plugins.html
[Pagination]: https://book.cakephp.org/2/en/core-libraries/components/pagination.html
[Retrieving Your Data]: https://book.cakephp.org/2/en/models/retrieving-your-data.html#creating-custom-find-types
4 changes: 2 additions & 2 deletions composer.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
},
"require-dev": {
"phpunit/phpunit": "<6.0.0",
"cakephp/cakephp": "^2.10.4",
"php-coveralls/php-coveralls": "^1.0"
"cakephp/cakephp": "^2.10",
"php-coveralls/php-coveralls": "^2.2"
}
}

0 comments on commit 99b8fde

Please sign in to comment.