Страничный вывод

Статистика: Символов — 9 599/8 180 без пробелов (5 859/5 038 без кода):, слов — 822
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Настройка ==
В некоторых фреймворках страничный вывод может быть большой проблемой. Страничный вывод в Laravel интегрирован с ((//docs/v5/queries построителем запросов)) и ((//docs/v5/eloquent Eloquent ORM)) и обеспечивает удобный, простой в использовании вывод результатов БД. Генерируемый HTML-код совместим с ((http://getbootstrap.com/ CSS-фреймворком Bootstrap)).

== Основы использования ==
=== Страничный вывод выборки из БД ===
Есть несколько способов разделения данных на страницы. Самый простой - используя метод %%paginate()%% на объекте-((docs/v5/queries конструкторе запросов)) или на запросе ((docs/v5/eloquent Eloquent)). Метод %%paginate()%% автоматически позаботится о задании правильных пределов и промежутков на основе текущей просматриваемой пользователем страницы. По умолчанию текущая страница определяется по значению аргумента %%(t)?page%% в HTTP-запросе. Само собой, Laravel автоматически определяет это значение, и так же автоматически вставляет его в ссылки, генерируемые для страничного вывода.

В этом примере единственный аргумент метода %%paginate()%% - число элементов на одной странице. Давайте укажем, что мы хотим выводить по **15** элементов на страницу:
%%
<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\DB;
//для версии 5.2 и ранее:
//use DB;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
  /**
   * Вывести всех пользователей приложения.
   *
   * @return Response
   */
  public function index()
  {
    $users = DB::table('users')->paginate(15);

    return view('user.index', ['users' => $users]);
  }
}
%%

.(alert)
На данный момент операции страничного вывода, которые используют оператор %%groupBy%%, не могут эффективно выполняться в Laravel. Если вам необходимо использовать %%groupBy%% для постраничного набора результатов, рекомендуется делать запрос в БД и создавать экземпляр страничного вывода вручную.

**"Простой страничный вывод"**

Если вам необходимо вывести для страничного представления только ссылки "Далее" и "Назад", вы можете использовать метод %%simplePaginate()%% для более эффективных запросов. Для больших наборов данных очень полезно, когда вам не надо отображать номер каждой страницы в вашем представлении:
%%
$users = DB::table('users')->simplePaginate(15);
%%

=== Страничный вывод запросов Eloquent ===
Можно также делать постраничный вывод запросов ((/docs/v5/eloquent Eloquent)). В этом примере мы разобьём на страницы модель %%(t)User%% по **15** элементов на странице. Как видите, синтаксис практически совпадает со страничным выводом выборки из БД:
%%
$users = App\User::paginate(15);
%%

Разумеется, вы можете вызвать %%paginate()%% после задания других условий запроса, таких как %%(t)where%%:
%%
$users = User::where('votes', '>', 100)->paginate(15);
%%

Также вы можете использовать метод %%simplePaginate()%% моделей Eloquent:
%%
$users = User::where('votes', '>', 100)->simplePaginate(15);
%%

=== Ручное создание экземпляра страничного вывода ===
Иногда необходимо создать экземпляр страничного вывода вручную, передав ему массив данных. Это можно сделать создав либо экземпляр %%(t)Illuminate\Pagination\Paginator%%, либо экземпляр %%(t)Illuminate\Pagination\LengthAwarePaginator%%, в зависимости от ситуации.

Классу %%(t)Paginator%% не надо знать общее количество элементов в конечном наборе, и поэтому класс не должен иметь методы для получения индекса последней страницы. %%(t)LengthAwarePaginator%% принимает почти те же аргументы, что и %%(t)Paginator%%, но ему требуется общее количество элементов в конечном наборе.

Другими словами, %%(t)Paginator%% соответствует методу %%simplePaginate()%% на конструкторе запросов и Eloquent, а %%(t)LengthAwarePaginator%% соответствует методу %%paginate()%%.

.(alert)
При ручном создании экземпляра страничного вывода вы должны вручную "поделить" передаваемый в него массив результатов. Если вы не знаете, как это сделать, используйте PHP-функцию ((https://secure.php.net/manual/en/function.array-slice.php array_slice)).

== Отображение результатов страничного вывода ==
При вызове методов %%paginate()%% и %%simplePaginate()%% на конструкторе запросов или запросе Eloquent вы получите экземпляр страничного вывода. Для метода %%paginate()%% это будет экземпляр %%(t)Illuminate\Pagination\LengthAwarePaginator%%. А для метода %%simplePaginate()%% это будет экземпляр %%(t)Illuminate\Pagination\Paginator%%. Эти объекты предоставляют несколько методов для вывода конечного набора. В дополнение к этим вспомогательным методам экземпляры страничного вывода - итераторы, к ним можно обращаться как к массивам. Итак, когда вы получили результаты, вы можете вывести их и создать ссылки на страницы с помощью ((//docs/v5/blade Blade)):
%%
<div class="container">
  @foreach ($users as $user)
    {{ $user->name }}
  @endforeach
</div>

{{ $users->links() }}
//для версии 5.1 и ранее:
//{!! $users->render() !!}
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Итак, когда вы получили результаты, вы можете вывести их и создать ссылки на страницы методом %%render()%%:
~%%
<div class="container">
  <?php foreach ($users as $user): ?>
    <?php echo $user->name; ?>
  <?php endforeach; ?>
</div>

<?php echo $users->render(); ?>
~%%
%%

Метод %%links()%% (для версии 5.1 и ранее %%render()%%) выведет ссылки на остальные страницы в конечном наборе. Каждая из этих ссылок уже будет содержать правильную переменную строки запроса %%(t)page%%. Помните, сгенерированный методом %%links()%% HTML-код совместим с ((https://getbootstrap.com/ CSS-фреймворком Bootstrap)).

%%(DOCNEW 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
.(alert)
При вызове метода %%render()%% из Blade-шаблона не забудьте использовать синтаксис %%{!! !!}%% для экранирования HTML-ссылок.
%%

**Настройка URI для вывода ссылок**

Настроить URI для вывода ссылок на страницы можно с помощью метода %%setPath()%%. Например, если вы хотите получить ссылки вида %%(t)http://example.com/custom/url?page=N%%, вам надо передать %%(t)custom/url%% в метод %%setPath()%%:
%%
Route::get('users', function () {
  $users = App\User::paginate(15);

  $users->setPath('custom/url');

  //
});
%%

**Параметры в ссылках**

Вы можете добавить параметры запросов к ссылкам страниц с помощью метода %%appends()%%. Например, чтобы добавить %%(t)&sort=votes%% к каждой страничной ссылке, вам надо вызвать %%appends()%% вот так:
%%
{{ $users->appends(['sort' => 'votes'])->links() }}
//для версии 5.1 и ранее:
//{!! $users->appends(['sort' => 'votes'])->render() !!}
%%

Код выше создаст ссылки наподобие:
%%(t)
http://example.com/something?page=2&sort=votes
%%

Если вы хотите добавить "хэш-фрагмент" в URL-адреса страничного вывода, вы можете использовать метод %%fragment()%%. Например, чтобы добавить %%(t)#foo%% к каждой страничной ссылке, вам надо вызвать %%fragment()%% вот так:
%%
{{ $users->fragment('foo')->links() }}
//для версии 5.1 и ранее:
//{!! $users->fragment('foo')->render() !!}
%%

Вызов этого метода сгенерирует URL-адреса наподобие:
%%(t)
http://example.com/something?page=2#foo
%%

=== Преобразование в JSON ===
Классы страничного вывода Laravel реализуют контракт интерфейса %%(t)Illuminate\Contracts\Support\Jsonable%% и предоставляют метод %%toJson()%%, поэтому можно очень легко конвертировать ваш страничный вывод в JSON. Вы также можете преобразовать экземпляр страничного вывода в JSON, просто вернув его из маршрута или действия контроллера.
%%
Route::get('users', function () {
  return App\User::paginate();
});
%%

JSON-форма экземпляра будет включать некоторые "мета-данные", такие как %%(t)total%%, %%(t)current_page%%, %%(t)last_page%% и другие. Данные экземпляра будут доступны через ключ %%(t)data%% в массиве JSON. Вот пример JSON, созданного при помощи возврата экземпляра страничного вывода из маршрута:
%%
{
 "total": 50,
 "per_page": 15,
 "current_page": 1,
 "last_page": 4,
 "next_page_url": "http://laravel.app?page=2",
 "prev_page_url": null,
 "from": 1,
 "to": 15,
 "data":[
    {
      // Объект вывода
    },
    {
      // Объект вывода
    }
 ]
}
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
== Настройка представления страничного вывода ==
По умолчанию отрисованные представления для отображения ссылок страничного вывода совместимы с CSS-фреймворком Bootstrap. Но если вы не используете Bootstrap, вы можете определить свои собственные представления для отрисовки этих ссылок. При вызове метода %%links()%% на экземпляре страничного вывода передайте первым аргументом имя представления:
~%%
{{ $paginator->links('view.name') }}
~%%

Но самый простой способ изменить представления страничного вывода - экспортировать их в ваш каталог %%(t)resources/views/vendor%% с помощью команды %%(sh)vendor:publish%%:
%%(sh)
php artisan vendor:publish --tag=laravel-pagination
~%%

Эта команда поместит представления в папку %%(t)resources/views/vendor/pagination%%. Файл %%(t)default.blade.php%% в этой папке является стандартным представлением страничного вывода. Просто отредактируйте этот файл, чтобы изменить HTML страничного вывода.
%%

== Методы экземпляра страничного вывода ==
Каждый экземпляр страничного вывода предоставляет дополнительную информацию с помощью этих методов:
  * %%$results->count()%%
  * %%$results->currentPage()%%
  * %%$results->firstItem()%% (для версии 5.2 и выше)
  * %%$results->hasMorePages()%%
  * %%$results->lastItem()%% (для версии 5.2 и выше)
  * %%$results->lastPage()%% (недоступен при использовании simplePaginate)
  * %%$results->nextPageUrl()%%
  * %%$results->perPage()%%
  * %%$results->previousPageUrl()%%
  * %%$results->total()%% (недоступен при использовании simplePaginate)
  * %%$results->url($page)%%
%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
    * %%firstItem()%%
    * %%lastItem()%%
%%