kyslik / column-sortable
Package for handling column sorting in Laravel 6.x
Installs: 3 909 598
Dependents: 25
Suggesters: 0
Security: 0
Stars: 644
Watchers: 18
Forks: 105
Open Issues: 39
Type:package
Requires
- php: >=7.2
- illuminate/database: 5.8.*|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
- illuminate/support: 5.8.*|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^5.0|^7.0|^8.0|^9.0
- phpunit/phpunit: ^8.5|^9.5.10|^10.5
- dev-master
- 6.6.0
- 6.5.0
- 6.4.2
- 6.4.1
- 6.4.0
- 6.3.0
- 6.2.1
- 6.2.0
- 6.1.0
- 6.0.0
- 5.8.0
- 5.7.0
- 5.6.3
- 5.6.2
- 5.6.1
- 5.6.0
- 5.5.8
- 5.5.7
- 5.5.6
- 5.5.5
- 5.5.4
- 5.5.3
- 5.5.2
- 5.5.1
- 5.5.0
- 5.4.11
- 5.4.10
- 5.4.9
- 5.4.8
- 5.4.7
- 5.4.6
- 5.4.5
- 5.4.4
- 5.4.3
- 5.4.2
- 5.4.1
- 5.4.0
- 5.3.10
- 5.3.9
- 5.3.8
- 5.3.7
- 5.3.6
- 5.3.5
- 5.3.4
- 5.3.3
- 5.3.2
- 5.3.1
- 5.3.0
- 5.2.10
- 5.2.9
- 5.2.8
- 5.2.7
- 5.2.6
- 5.2.5
- 5.2.4
- 5.2.3
- 5.2.2
- 5.2.1
- 5.2.0
- 5.1.14
- 5.1.13
- 5.1.12
- 5.1.11
- 5.1.10
- 5.1.9
- 5.1.8
- 5.1.7
- 5.1.6
- 5.1.5
- 5.1.4
- 5.1.3
- 5.1.2
- 5.1.1
- 5.1.0
- 5.0.9
- 5.0.8
- 5.0.7
- 5.0.6
- 5.0.5
- 5.0.4
- 5.0.3
- 5.0.2
- 5.0.1
- 5.0.0
- 4.0.1
- 4.0.0
- 3.0.6
- 3.0.0
- 2.0.2
- 2.0.0
- dev-healyhatman-custom-hrefs
- dev-L6
- dev-L6.1
- dev-L6.0
- dev-L5.8
- dev-L5.5-7
- dev-L5.5-6
- dev-L5.4
- dev-L5.1-3
- dev-L5.5
- dev-L5.1
- dev-L5.2
- dev-L5.3
This package is auto-updated.
Last update: 2024-10-30 00:36:14 UTC
README
Package for handling column sorting in Laravel 5.[5-8]. For earlier versions of Laravel checkout branch L5.1-3
- Column sorting for Laravel 5.5-10
- Setup
- Usage
- HasOne / BelongsTo Relation sorting
- ColumnSortable overriding (advanced)
- Aliasing
- Exception to catch
Setup
Composer
Pull this package in through Composer (development/latest version dev-master
)
{ "require": { "kyslik/column-sortable": "^6.0" } }
composer update
Laravel's >=5.5 auto discovery
Simply install the package and let Laravel do its magic.
Note
(pre Laravel 6.0)**: major and minor versions should match with Laravel's version, for example if you are using Laravel 5.4, column-sortable version should be 5.4.*
.
Manual installation (pre 5.5)
Add the service provider to array of providers in config/app.php
'providers' => [ App\Providers\RouteServiceProvider::class, /* * Third Party Service Providers... */ Kyslik\ColumnSortable\ColumnSortableServiceProvider::class, ],
Publish configuration
Publish the package configuration file to your application.
php artisan vendor:publish --provider="Kyslik\ColumnSortable\ColumnSortableServiceProvider" --tag="config"
See configuration file (config/columnsortable.php
) yourself and make adjustments as you wish.
Usage
Use Sortable trait inside your Eloquent model(s). Define $sortable
array (see example code below).
Note
Scheme::hasColumn()
is run only when $sortable
is not defined - less DB hits per request.
use Kyslik\ColumnSortable\Sortable; class User extends Model implements AuthenticatableContract, CanResetPasswordContract { use Authenticatable, CanResetPassword, Sortable; ... public $sortable = ['id', 'name', 'email', 'created_at', 'updated_at']; ... }
You're set to go.
Sortable trait adds Sortable scope to the models so you can use it with paginate.
Blade Extension
There is a blade extension for you to use @sortablelink()
@sortablelink('column', 'Title', ['parameter' => 'smile'], ['rel' => 'nofollow'])
Column (1st) parameter is column in database, Title (2nd) parameter is displayed inside anchor tags, array()
parameter (3rd) is default (GET) query strings parameter and array()
parameter (4th) is for additional anchor-tag attributes. You can use a custom URL as 'href' attribute in the 4th parameter, and the query string will be appended to it.
You can omit 2nd, 3rd and 4th parameter.
Possible examples and usages of blade extension:
@sortablelink('name') @sortablelink('name', 'Username') @sortablelink('address', trans('fields.address'), ['filter' => 'active, visible']) @sortablelink('address', trans('fields.address'), ['filter' => 'active, visible'], ['class' => 'btn btn-block', 'rel' => 'nofollow', 'href' => route('my.custom.route')])
If you do not fill Title (2nd parameter) column name is used instead.
Note
you can set default formatting function that is applied on Title (2nd parameter), by default this is set to ucfirst
.
Configuration in few words
Sortablelink blade extension distinguishes between types (numeric, amount and alpha) and applies different class for each of them.
See following snippet:
'columns' => [ 'numeric' => [ 'rows' => ['created_at', 'updated_at', 'level', 'id'], 'class' => 'fa fa-sort-numeric' ], 'amount' => [ 'rows' => ['price'], 'class' => 'fa fa-sort-amount' ], 'alpha' => [ 'rows' => ['name', 'description', 'email', 'slug'], 'class' => 'fa fa-sort-alpha', ], ],
Rest of the config file should be crystal clear and I advise you to skim it.
Font Awesome (default font classes)
Install Font-Awesome for visual Joy. Search "sort" in cheatsheet and see used icons (12) yourself.
Font Awesome 5
Change the suffix class in the config file from -asc
/-desc
(FA 4) to -up
/-down
(FA 5) respectively.
/* this is FA 5 compatible. suffix class that is appended when ascending direction is applied */ 'asc_suffix' => '-up', /* suffix class that is appended when descending direction is applied */ 'desc_suffix' => '-down',
Note
If you haven't published the config yet, follow the instructions above.
Full Example
You may be interested in working example repository, where package usage is demonstrated.
Routes
Route::get('users', ['as' => 'users.index', 'uses' => 'HomeController@index']);
Controller's index()
method
public function index(User $user) { $users = $user->sortable()->paginate(10); return view('user.index')->withUsers($users); }
You can set default sorting parameters which will be applied when URL is empty.
For example: page is loaded for first time, default direction is configurable (asc)
$users = $user->sortable('name')->paginate(10); // produces ->orderBy('users.name', 'asc') $users = $user->sortable(['name'])->paginate(10); // produces ->orderBy('users.name', 'asc') $users = $user->sortable(['name' => 'desc'])->paginate(10); // produces ->orderBy('users.name', 'desc')
View (pagination included)
@sortablelink('id', 'Id') @sortablelink('name') @foreach ($users as $user) {{ $user->name }} @endforeach {!! $users->appends(\Request::except('page'))->render() !!}
Note
Blade's ability to recognize directives depends on having space before directive itself <tr> @sortablelink('Name')
HasOne / BelongsTo Relation sorting
Define hasOne relation
In order to make relation sorting work, you have to define hasOne() relation in your model.
/** * Get the user_detail record associated with the user. */ public function detail() { return $this->hasOne(App\UserDetail::class); }
Define belongsTo relation
Note
in case there is a self-referencing model (like comments, categories etc.); parent table will be aliased with parent_
string, for more information see issue #60.
/** * Get the user that owns the phone. */ public function user() { return $this->belongsTo(App\User::class); }
In User model we define hasOne relation to UserDetail model (which holds phone number and address details).
Define $sortable
arrays
Define $sortable
array in both models (else, package uses Scheme::hasColumn()
which is an extra database query).
for User
public $sortable = ['id', 'name', 'email', 'created_at', 'updated_at'];
for UserDetail
public $sortable = ['address', 'phone_number'];
Blade and relation sorting
In order to tell package to sort using relation:
@sortablelink('detail.phone_number', 'phone') @sortablelink('user.name', 'name')
Note
package works with relation "name" (method) that you define in model instead of table name.
Warning
do not use combination of two different relations at the same time, you are going to get errors that relation is not defined
In config file you can set your own separator in case .
(dot) is not what you want.
'uri_relation_column_separator' => '.'
ColumnSortable overriding (advanced)
It is possible to override ColumnSortable relation feature, basically you can write your own join(s) / queries and apply orderBy()
manually.
See example:
class User extends Model { use Sortable; public $sortable = ['name']; ... public function addressSortable($query, $direction) { return $query->join('user_details', 'users.id', '=', 'user_details.user_id') ->orderBy('address', $direction) ->select('users.*'); } ...
Controller is the same $users = $user->sortable()->paginate(10);
In view just use @sortablelink('address')
Huge thanks to @neutralrockets and his comments on #8. Another example on how to use overriding is issue #41.
Aliasing
It is possible to declare $sortableAs
array and use it to alias (bypass column exists check), and ignore prefixing with table.
In model
... $sortableAs = ['nick_name']; ...
In controller
$users = $user->select(['name as nick_name'])->sortable(['nick_name'])->paginate(10);
In view
@sortablelink('nick_name', 'nick')
See #44 for more information on aliasing.
Using withCount()
Aliasing is useful when you want to sort results with withCount()
, see issue #49 for more information.
Exception to catch
Package throws custom exception ColumnSortableException
with three codes (0, 1, 2).
Code 0 means that explode()
fails to explode URI parameter "sort" in to two values.
For example: sort=detail..phone_number
- produces array with size of 3, which causes package to throw exception with code 0.
Code 1 means that $query->getRelation()
method fails, that means when relation name is invalid (does not exists, is not declared in model).
Code 2 means that provided relation through sort argument is not instance of hasOne.
Example how to catch:
... try { $users = $user->with('detail')->sortable(['detail.phone_number'])->paginate(5); } catch (\Kyslik\ColumnSortable\Exceptions\ColumnSortableException $e) { dd($e); }
Note
I strongly recommend to catch ColumnSortableException because there is a user input in question (GET parameter) and any user can modify it in such way that package throws ColumnSortableException with code 0
.