Laravel - Database - Pagination (官方文件原子化翻譯)

# 前言

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。

# Basic Usage

# Paginating Query Builder Results

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Http\Controllers;
  
  use App\Http\Controllers\Controller;
  use Illuminate\Support\Facades\DB;
  
  class UserController extends Controller
  {
      public function index()
      {
          $users = DB::table('users')->paginate(15);
  
          return view('user.index', ['users' => $users]);
      }
  }

• Answer:
  分頁處理 users table query builder 的結果

以下的 Laravel example code 的意思是？

• Example:

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

• Answer:
  paginate users table 的 query 結果, 不顯示分頁頁數, 只提供上一頁跟下一頁的 link, 效能較佳

# Paginating Eloquent Results

以下的 Laravel example code 的意思是？

• Example:

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

• Answer:
  paginate User model Eloquent queries 結果, 每頁 15 筆資料

以下的 Laravel example code 的意思是？

• Example:

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

• Answer:
  simple paginate User model Eloquent queries 結果, 每頁 15 筆資料, 差別在於不提供頁數號碼, 只提供上一頁跟下一頁的 link

# Manually Creating A Paginator

Laravel 中, Paginator 與 LengthAwarePaginator 的差異是？

Paginator 不需要知道共有幾筆資料, 所以也無法直接取得最後一筆資料
LengthAwarePaginator 需要知道共有幾筆資料

# Displaying Pagination Results

Customizing The Paginator URI

Laravel 中, 以下的 example 的意思是？

• Example:

  <?php
  Route::get('users', function () {
      $users = App\Models\User::paginate(15);
  
      $users->withPath('custom/url');
  
      //
  });

• Answer:
  客製化 paginator 的 links, 像是 http://example.com/custom/url?page=N

Appending To Pagination Links

Laravel 中, 以下的 example 的意思是？

• Example:

  <?php
  {{ $users->appends(['sort' => 'votes'])->links() }}

• Answer:
  將 ['sort' => 'votes'] 附加到 pagination link 的 query

Laravel 中, 以下的 example 的意思是？

• Example:

  <?php
  {{ $users->withQueryString()->links() }}

• Answer:
  將所有的 querystring 都附加到 pagination link

Laravel 中, 以下的 example 的意思是？

• Example:

  <?php
  {{ $users->fragment('foo')->links() }}

• Answer:
  附加 fragment 到 pagination links, 像是 http://www.example.org/foo.html#foo

Displaying Pagination Results

以下的 Laravel example code 的意思是？

• Example:

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

• Answer:
  當 $users 為 Paginator 或 LengthAwarePaginator instance 時, 可使用 link() 取得導向剩下結果的每一頁的 link

# Adjusting The Pagination Link Window

以下的 Laravel example code 的意思是？

• Example:

  <?php
  {{ $users->onEachSide(5)->links() }}

• Answer:
  當使用 Paginator 或 LengthAwarePaginator 的 link() 時, 預設會顯示 current page 左右各三頁的 link, 如果要自定義, 可使用 onEachSide()

# Converting Results To JSON

Laravel 中, 以下的 example 的意思是？

• Example:

  <?php
  Route::get('users', function () {
      return App\Models\User::paginate();
  });

• Answer:
  return JSON 格式的 pagination object, 如下
• Output:

  {
     "total": 50,
     "per_page": 15,
     "current_page": 1,
     "last_page": 4,
     "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":[
          {
              // Record...
          },
          {
              // Record...
          }
     ]
  }

# Customizing The Pagination View

以下的 Laravel example code 的意思是？

• Example:

  <?php
  {{ $paginator->links('view.name') }}
  
  // Passing additional data to the view...
  {{ $paginator->links('view.name', ['foo' => 'bar']) }}

• Answer:
  Laravel Paginator 預設是使用 Tailwind CSS 的, 但如果要自定義的話, 可以 pass 指定的 view, 以及 additional parameters

以下的 Laravel example command 的意思是？

• Example:

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

• Answer:
  可匯出內建的 Paginator view blade 到 resources/views/vendor/pagination 資料夾, 可編輯其中的 tailwind.blade.php 來修改 pagination HTML

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Providers;
  
  use Illuminate\Pagination\Paginator;
  use Illuminate\Support\Facades\Blade;
  use Illuminate\Support\ServiceProvider;
  
  class AppServiceProvider extends ServiceProvider
  {
      public function boot()
      {
          Paginator::defaultView('view-name');
  
          Paginator::defaultSimpleView('view-name');
      }
  }

• Answer:
  在 AppServiceProvider boot() 中, 可使用 defaultView 以及 defaultSimpleView 來定義 Paginator, simple paginator 的 default view file name, 可將 view file 置於 resources/views/vendor/pagination/

# Using Bootstrap

以下的 Laravel example code 的意思是？

• Example:

  <?php
  // 位於 AppServiceProvider
  use Illuminate\Pagination\Paginator;
  
  public function boot()
  {
      Paginator::useBootstrap();
  }

• Answer:
  Laravel Paginator view 預設是使用 tailwind CSS, 但如果要使用 bootstrap, 可在 AppServiceProvider boot() 中, 使用 useBootstrap()

# Paginator Instance Methods

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->count()	

• Answer:
  取得 current page 有幾個 item

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->currentPage()	

• Answer:
  取得 current page number

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->firstItem()	

• Answer:
  取得 first item number

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->getOptions()	

• Answer:
  取得 paginator options

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->getUrlRange($start, $end)

• Answer:
  建立一組指定範圍內的 URLs

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->hasPages()

• Answer:
  確認是否有足夠的 item 來形成第二頁

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->hasMorePages()

• Answer:
  確認當前頁是否為最後一頁 (是否還有更多 item)

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->items()

• Answer:
  取得 current page items

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->lastItem()

• Answer:
  取得 current page last item

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->lastPage()

• Answer:
  取得 last page number (simple paginator 不適用)

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->nextPageUrl()

• Answer:
  取得 next page url

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->onFirstPage()

• Answer:
  判斷是否為 first page

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->perPage()

• Answer:
  取得每頁有幾個 item

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->previousPageUrl()

• Answer:
  取得 previous page url

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->total()

• Answer:
  取得 data store item 總數

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->url($page)

• Answer:
  取得指定 $page 的 url

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->getPageName()

• Answer:
  取得 ‘page’ 的 query string name, Laravel 預設為 ‘page’, 可自己修改, 所以不一定叫做 page, 透過這個 method 可取得

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $paginator->setPageName($name)

• Answer:
  Laravel paginator 預設 query string 代表第幾頁的為 ‘page’, 例如 example.com/whatever?page=3, 可使用 setPageName 修改, 假設 setPageName('egap'), 那 url 則為 example.com/whatever?egap=3