work on pagination docs.

pagination.md

@@ -1,19 +1,27 @@
 # Pagination
 
-- [Paginating Database Records](#paginating-database-records)
-- [Displaying Results](#displaying-results)
+- [Introduction](#introduction)
+- [Basic Usage](#basic-usage)
+ - [Paginating Query Builder Results](#paginating-query-builder-results)
+ - [Paginating Eloquent Results](#paginating-eloquent-results)
+ - [Manually Creating A Paginator](#manually-creating-a-paginator)
+- [Displaying Results In A View](#displaying-results-in-a-view)
 - [Converting Results To JSON](#converting-results-to-json)
 
-<a name="paginating-database-records"></a>
-## Paginating Database Records
+<a name="introduction"></a>
+## Introduction
 
 In other frameworks, pagination can be very painful. Laravel makes it a breeze. Laravel can quickly generate an intelligent "range" of links based on the current page, and the generated HTML is compatible with the [Bootstrap CSS framework](https://getbootstrap.com/).
 
-There are several ways to paginate items. The simplest is by using the `paginate` method on the [query builder](/docs/{{version}}/queries) or an [Eloquent query](/docs/{{version}}/eloquent). The `paginate` method provided by Laravel automatically takes care of setting the proper limit and offset based on the current page being viewed by the user. By default, the current page is detected by the value of the `?page` query string argument. Of course, this value is automatically detected by Laravel, and is also automatically inserted into links generated by the paginator.
+<a name="basic-usage"></a>
+## Basic Usage
 
+<a name="paginating-query-builder-results"></a>
 ### Paginating Query Builder Results
 
-First, let's take a look at calling the `paginate` method on a query generated by the query builder:
+There are several ways to paginate items. The simplest is by using the `paginate` method on the [query builder](/docs/{{version}}/queries) or an [Eloquent query](/docs/{{version}}/eloquent). The `paginate` method provided by Laravel automatically takes care of setting the proper limit and offset based on the current page being viewed by the user. By default, the current page is detected by the value of the `?page` query string argument on the HTTP request. Of course, this value is automatically detected by Laravel, and is also automatically inserted into links generated by the paginator.
+
+First, let's take a look at calling the `paginate` method on a query. In this example, the only argument passed to `paginate` is the number of items you would like displayed "per page". In this case, let's specify that we would like to display `15` items per page:
 
  <?php namespace App\Http\Controllers;
 
@@ -35,36 +43,42 @@ First, let's take a look at calling the `paginate` method on a query generated b
   }
  }
 
-In this example, the only argument passed to `paginate` is the number of items we would like displayed "per page". In this case, we specified that we would like to display `15` items per page.
-
 > **Note:** Currently, pagination operations that use a `groupBy` statement cannot be executed efficiently by Laravel. If you need to use a `groupBy` with a paginated result set, it is recommended that you query the database and create a paginator manually.
 
-### Paginating Eloquent Models
+#### "Simple Pagination"
 
-You may also paginate [Eloquent](/docs/{{version}}/eloquent) queries. In this example, we will paginate the `User` model with `15` items per page. As you can see, the syntax is nearly identical to paginating query builder results:
+If you are only showing "Next" and "Previous" links in your pagination view, you have the option of using the `simplePaginate` method to perform a more efficient query. This is very useful for large datasets if you do not need to display a link for each page number when rendering your view:
 
- $allUsers = User::paginate(15);
+ $users = DB::table('users')->simplePaginate(15);
 
-Of course, you may call `paginate` after setting other constraints on the query:
+<a name="paginating-eloquent-results"></a>
+### Paginating Eloquent Results
 
- $someUsers = User::where('votes', '>', 100)->paginate(15);
+You may also paginate [Eloquent](/docs/{{version}}/eloquent) queries. In this example, we will paginate the `User` model with `15` items per page. As you can see, the syntax is nearly identical to paginating query builder results:
 
-#### "Simple Pagination"
+ $users = App\User::paginate(15);
 
-If you are only showing "Next" and "Previous" links in your pagination view, you have the option of using the `simplePaginate` method to perform a more efficient query. This is very useful for large datasets if you do not need to display a link for each page number when rendering your view:
+Of course, you may call `paginate` after setting other constraints on the query, such as `where` clauses:
+
+ $users = User::where('votes', '>', 100)->paginate(15);
 
- $someUsers = User::where('votes', '>', 100)->simplePaginate(15);
+You may also use the `simplePaginate` method when paginating Eloquent models:
 
-### Creating A Paginator Manually
+ $users = User::where('votes', '>', 100)->simplePaginate(15);
+
+<a name="manually-creating-a-paginator"></a>
+### Manually Creating A Paginator
 
 Sometimes you may wish to create a pagination instance manually, passing it an array of items. You may do so by creating either an `Illuminate\Pagination\Paginator` or `Illuminate\Pagination\LengthAwarePaginator` instance, depending on your needs.
 
-The `Paginator` class does not need to know the total number of items in the result set; however, because of this, the class does not have methods for retrieve the index of the last page. The `LengthAwarePaginator` accepts almost the same arguments as the `Paginator`, except that it does require a count of the total number of items in the result set.
+The `Paginator` class does not need to know the total number of items in the result set; however, because of this, the class does not have methods for retrieve the index of the last page. The `LengthAwarePaginator` accepts almost the same arguments as the `Paginator`; however, it does require a count of the total number of items in the result set.
 
 In other words, the `Paginator` corresponds to the `simplePaginate` method on the query builder and Eloquent, while the `LengthAwarePaginator` corresponds to the `paginate` method.
 
-<a name="displaying-results"></a>
-## Displaying Results
+When manually creating a paginator instance, you should manually "slice" the array of results you pass to the paginator. If you're unsure how to do this, check out the [array_slice](https://php.net/manual/en/function.array-slice.php) PHP function.
+
+<a name="displaying-results-in-a-view"></a>
+## Displaying Results In A View
 
 When you call the `paginate` or `simplePaginate` methods on a query builder or Eloquent query, you will receive a paginator instance. When calling the `paginate` method, you will receive an instance of `Illuminate\Pagination\LengthAwarePaginator`. When calling the `simplePaginate` method, you will receive an instance of `Illuminate\Pagination\Paginator`. These objects provide several methods that describe the result set. In addition to these helpers methods, the paginator instances are iterators and may be looped as an array.
 
@@ -86,7 +100,13 @@ The `render` method will render the links to the rest of the pages in the result
 
 The `setPath` method allows you to customize the URI used by the paginator when generating links. For example, if you want the paginator to generate links like `https://example.com/custom/url?page=N`, you should pass `custom/url` to the `setPath` method:
 
- $results->setPath('custom/url');
+ Route::get('users', function () {
+  $users = App\User::paginate(15);
+
+  $users->setPath('custom/url');
+
+  //
+ });
 
 #### Appending To Pagination Links
 
@@ -114,15 +134,15 @@ You may also access additional pagination information via the following methods
 <a name="converting-results-to-json"></a>
 ## Converting Results To JSON
 
-The Laravel paginator result classes implement the `Illuminate\Contracts\Support\JsonableInterface` contract and exposes the `toJson` method, so it's very easy to convert your pagination results to JSON.
+The Laravel paginator result classes implement the `Illuminate\Contracts\Support\JsonableInterface` contract and expose the `toJson` method, so it's very easy to convert your pagination results to JSON.
 
 You may also convert a pagintor instance to JSON by simply returning it from a route or controller action:
 
- Route::get('users/paginate', function() {
+ Route::get('users', function () {
   return App\User::paginate();
  });
 
-The JSON form of the paginator will include meta information such as `total`, `current_page`, `last_page`, and more. The actual result objects will be available via the `data` key in the JSON array. Here is an example of the JSON created by returning a paginator instance from a route:
+The JSON from of the paginator will include meta information such as `total`, `current_page`, `last_page`, and more. The actual result objects will be available via the `data` key in the JSON array. Here is an example of the JSON created by returning a paginator instance from a route:
 
 #### Example Paginator JSON