Пагінація · Laravel

В інших фреймворках пагінація буває справжнім болем. Сподіваємось, підхід Laravel стане ковтком свіжого повітря. Пагінатор Laravel інтегрований із конструктором запитів та Eloquent ORM і дає зручну пагінацію записів із бази даних без жодного налаштування.

За замовчуванням HTML, який генерує пагінатор, сумісний із фреймворком Tailwind CSS; утім, підтримка пагінації в стилі Bootstrap теж доступна.

Tailwind

Якщо ви користуєтесь стандартними Tailwind-представленнями пагінації Laravel разом із Tailwind 4.x, файл resources/css/app.css вашого застосунку вже буде налаштований так, щоб указувати @source на представлення пагінації Laravel:

@import 'tailwindcss';

@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';

Базове використання

Пагінація результатів конструктора запитів

Розбити елементи на сторінки можна кількома способами. Найпростіший - метод paginate на конструкторі запитів або на запиті Eloquent. Метод paginate сам подбає про встановлення "limit" і "offset" запиту відповідно до сторінки, яку зараз переглядає користувач. За замовчуванням поточна сторінка визначається зі значення аргументу page у рядку запиту HTTP-запиту. Laravel визначає це значення автоматично і так само автоматично підставляє його в посилання, які генерує пагінатор.

У цьому прикладі єдиний аргумент, переданий у метод paginate, - кількість елементів, які ви хочете показувати "на сторінку". Вкажімо, що хочемо показувати 15 елементів на сторінку:

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * Показати всіх користувачів застосунку.
     */
    public function index(): View
    {
        return view('user.index', [
            'users' => DB::table('users')->paginate(15)
        ]);
    }
}

Проста пагінація

Метод paginate рахує загальну кількість записів, які відповідають запиту, перед тим як дістати самі записи з бази даних. Так пагінатор дізнається, скільки всього є сторінок із записами. Проте якщо ви не плануєте показувати загальну кількість сторінок в інтерфейсі застосунку, запит на підрахунок записів зайвий.

Тому, якщо вам потрібні лише прості посилання "Далі" й "Назад", скористайтесь методом simplePaginate, який виконує один ефективний запит:

$users = DB::table('users')->simplePaginate(15);

Пагінація результатів Eloquent

Розбивати на сторінки можна й запити Eloquent. У цьому прикладі ми пагінуємо модель App\Models\User і вказуємо, що плануємо показувати 15 записів на сторінку. Як бачите, синтаксис майже не відрізняється від пагінації результатів конструктора запитів:

use App\Models\User;

$users = User::paginate(15);

Звісно, метод paginate можна викликати після того, як ви наклали на запит інші обмеження, наприклад умови where:

$users = User::where('votes', '>', 100)->paginate(15);

Із моделями Eloquent так само працює метод simplePaginate:

$users = User::where('votes', '>', 100)->simplePaginate(15);

Аналогічно метод cursorPaginate дає курсорну пагінацію моделей Eloquent:

$users = User::where('votes', '>', 100)->cursorPaginate(15);

Кілька екземплярів пагінатора на сторінці

Іноді потрібно вивести два окремі пагінатори на одному екрані. Якщо обидва екземпляри пагінатора зберігають поточну сторінку в параметрі page рядка запиту, вони конфліктуватимуть. Щоб цього уникнути, передайте назву параметра рядка запиту, у якому треба зберігати поточну сторінку пагінатора, третім аргументом методів paginate, simplePaginate і cursorPaginate:

use App\Models\User;

$users = User::where('votes', '>', 100)->paginate(
    $perPage = 15, $columns = ['*'], $pageName = 'users'
);

Курсорна пагінація

Тоді як paginate і simplePaginate будують запити з SQL-конструкцією "offset", курсорна пагінація працює через умови "where", які порівнюють значення колонок сортування в запиті. Це дає найкращу продуктивність бази даних серед усіх способів пагінації в Laravel. Такий підхід особливо добре пасує великим наборам даних і інтерфейсам із "нескінченним" прокручуванням.

На відміну від пагінації за зміщенням, яка додає номер сторінки в рядок запиту згенерованих URL, курсорна пагінація кладе в рядок запиту рядок-"курсор". Курсор - це закодований рядок, у якому міститься позиція, з якої наступний запит має продовжити пагінацію, і напрямок руху:

http://localhost/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

Створити екземпляр курсорного пагінатора можна методом cursorPaginate конструктора запитів. Метод повертає екземпляр Illuminate\Pagination\CursorPaginator:

$users = DB::table('users')->orderBy('id')->cursorPaginate(15);

Отримавши екземпляр курсорного пагінатора, ви можете показати результати пагінації так само, як робите це з paginate і simplePaginate. Докладніше про методи екземпляра курсорного пагінатора читайте в документації методів курсорного пагінатора.

Увага Ваш запит має містити конструкцію "order by", щоб скористатися курсорною пагінацією. До того ж колонки, за якими сортується запит, мають належати таблиці, яку ви пагінуєте.

Курсорна пагінація проти пагінації за зміщенням

Щоб показати різницю між пагінацією за зміщенням і курсорною, розгляньмо приклади SQL-запитів. Обидва запити нижче виведуть "другу сторінку" результатів таблиці users, відсортованої за id:

# Пагінація за зміщенням...
select * from users order by id asc limit 15 offset 15;

# Курсорна пагінація...
select * from users where id > 15 order by id asc limit 15;

Запит курсорної пагінації має такі переваги над пагінацією за зміщенням:

• На великих наборах даних курсорна пагінація працюватиме швидше, якщо колонки з "order by" проіндексовані. Причина в тому, що конструкція "offset" сканує всі попередні знайдені дані.
• На наборах даних із частими записами пагінація за зміщенням може пропускати записи або показувати дублікати, якщо результати нещодавно додали чи видалили зі сторінки, яку зараз переглядає користувач.

Але курсорна пагінація має такі обмеження:

• Як і simplePaginate, курсорна пагінація придатна лише для показу посилань "Далі" й "Назад" і не підтримує генерації посилань із номерами сторінок.
• Вона вимагає, щоб сортування спиралося щонайменше на одну унікальну колонку або на комбінацію колонок, унікальну разом. Колонки зі значеннями null не підтримуються.
• Вирази запиту в конструкціях "order by" підтримуються лише тоді, коли для них задано псевдонім і їх також додано в конструкцію "select".
• Вирази запиту з параметрами не підтримуються.

Створення пагінатора вручну

Іноді потрібно створити екземпляр пагінації вручну, передавши йому масив елементів, які вже є в памʼяті. Зробити це можна, створивши екземпляр Illuminate\Pagination\Paginator, Illuminate\Pagination\LengthAwarePaginator або Illuminate\Pagination\CursorPaginator, залежно від ваших потреб.

Класам Paginator і CursorPaginator не потрібно знати загальну кількість елементів у наборі результатів; але через це вони й не мають методів для отримання індексу останньої сторінки. LengthAwarePaginator приймає майже ті самі аргументи, що й Paginator, проте вимагає кількість елементів у наборі результатів.

Інакше кажучи, Paginator відповідає методу simplePaginate конструктора запитів, CursorPaginator - методу cursorPaginate, а LengthAwarePaginator - методу paginate.

Увага Створюючи екземпляр пагінатора вручну, ви маєте самі "нарізати" масив результатів, який передаєте в пагінатор. Якщо не впевнені, як це зробити, погляньте на PHP-функцію array_slice.

Налаштування URL пагінації

За замовчуванням посилання, які генерує пагінатор, збігаються з URI поточного запиту. Проте метод withPath дозволяє змінити URI, який пагінатор використовує при генерації посилань. Наприклад, якщо ви хочете, щоб пагінатор генерував посилання виду http://example.com/admin/users?page=N, передайте /admin/users у метод withPath:

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->withPath('/admin/users');

    // ...
});

Додавання значень до рядка запиту

Додати значення до рядка запиту посилань пагінації можна методом appends. Наприклад, щоб дописати sort=votes до кожного посилання пагінації, викличте appends так:

use App\Models\User;

Route::get('/users', function () {
    $users = User::paginate(15);

    $users->appends(['sort' => 'votes']);

    // ...
});

Якщо ви хочете дописати до посилань пагінації всі значення рядка запиту з поточного запиту, скористайтесь методом withQueryString:

$users = User::paginate(15)->withQueryString();

Додавання хеш-фрагментів

Якщо треба дописати "хеш-фрагмент" до URL, які генерує пагінатор, скористайтесь методом fragment. Наприклад, щоб додати #users у кінець кожного посилання пагінації, викличте метод fragment ось так:

$users = User::paginate(15)->fragment('users');

Показ результатів пагінації

Викликаючи метод paginate, ви отримаєте екземпляр Illuminate\Pagination\LengthAwarePaginator, тоді як виклик simplePaginate повертає екземпляр Illuminate\Pagination\Paginator. І нарешті, виклик cursorPaginate повертає екземпляр Illuminate\Pagination\CursorPaginator.

Ці обʼєкти дають кілька методів, які описують набір результатів. Крім цих допоміжних методів, екземпляри пагінатора є ітераторами, тож їх можна перебирати як масив. Отже, отримавши результати, ви можете показати їх і відрендерити посилання на сторінки за допомогою Blade:

<div class="container">
    @foreach ($users as $user)
        {{ $user->name }}
    @endforeach
</div>

{{ $users->links() }}

Метод links відрендерить посилання на решту сторінок набору результатів. Кожне з цих посилань уже міститиме правильну змінну page в рядку запиту. Памʼятайте: HTML, згенерований методом links, сумісний із фреймворком Tailwind CSS.

Налаштування вікна посилань пагінації

Коли пагінатор показує посилання пагінації, він виводить номер поточної сторінки, а також посилання на три сторінки до й три після неї. Методом onEachSide ви можете керувати тим, скільки додаткових посилань показувати з кожного боку від поточної сторінки в середньому, рухомому вікні посилань, яке генерує пагінатор:

{{ $users->onEachSide(5)->links() }}

Перетворення результатів на JSON

Класи пагінатора Laravel реалізують контракт інтерфейсу Illuminate\Contracts\Support\Jsonable і надають метод toJson, тож перетворити результати пагінації на JSON дуже просто. Ви також можете перетворити екземпляр пагінатора на JSON, повернувши його з маршруту або дії контролера:

use App\Models\User;

Route::get('/users', function () {
    return User::paginate();
});

JSON із пагінатора міститиме метаінформацію на кшталт total, current_page, last_page тощо. Самі записи результатів доступні за ключем data у JSON-масиві. Ось приклад JSON, створеного поверненням екземпляра пагінатора з маршруту:

{
   "total": 50,
   "per_page": 15,
   "current_page": 1,
   "last_page": 4,
   "current_page_url": "http://laravel.app?page=1",
   "first_page_url": "http://laravel.app?page=1",
   "last_page_url": "http://laravel.app?page=4",
   "next_page_url": "http://laravel.app?page=2",
   "prev_page_url": null,
   "path": "http://laravel.app",
   "from": 1,
   "to": 15,
   "data":[
        {
            // Запис...
        },
        {
            // Запис...
        }
   ]
}

Налаштування представлення пагінації

За замовчуванням представлення, які рендеряться для показу посилань пагінації, сумісні з фреймворком Tailwind CSS. Проте якщо ви не використовуєте Tailwind, ви вільні описати власні представлення для рендерингу цих посилань. Викликаючи метод links на екземплярі пагінатора, передайте назву представлення першим аргументом:

{{ $paginator->links('view.name') }}

<!-- Передача додаткових даних у представлення... -->
{{ $paginator->links('view.name', ['foo' => 'bar']) }}

Проте найпростіший спосіб налаштувати представлення пагінації - експортувати їх у теку resources/views/vendor командою vendor:publish:

php artisan vendor:publish --tag=laravel-pagination

Ця команда покладе представлення в теку resources/views/vendor/pagination вашого застосунку. Файл tailwind.blade.php у цій теці відповідає стандартному представленню пагінації. Відредагуйте його, щоб змінити HTML пагінації.

Якщо ви хочете призначити стандартним представленням пагінації інший файл, викличте методи пагінатора defaultView і defaultSimpleView у методі boot класу App\Providers\AppServiceProvider:

<?php

namespace App\Providers;

use Illuminate\Pagination\Paginator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Ініціалізація будь-яких сервісів застосунку.
     */
    public function boot(): void
    {
        Paginator::defaultView('view-name');

        Paginator::defaultSimpleView('view-name');
    }
}

Використання Bootstrap

Laravel містить представлення пагінації, зроблені на Bootstrap CSS. Щоб використати їх замість стандартних Tailwind-представлень, викличте методи пагінатора useBootstrapFour або useBootstrapFive у методі boot класу App\Providers\AppServiceProvider:

use Illuminate\Pagination\Paginator;

/**
 * Ініціалізація будь-яких сервісів застосунку.
 */
public function boot(): void
{
    Paginator::useBootstrapFive();
    Paginator::useBootstrapFour();
}

Методи екземпляра Paginator / LengthAwarePaginator

Кожен екземпляр пагінатора дає додаткову інформацію про пагінацію через такі методи:

Методи екземпляра курсорного пагінатора

Кожен екземпляр курсорного пагінатора дає додаткову інформацію про пагінацію через такі методи: