{"id":14974731,"url":"https://github.com/apphp/laravel-datagrid","last_synced_at":"2025-10-27T09:31:29.437Z","repository":{"id":62486356,"uuid":"323171280","full_name":"apphp/laravel-datagrid","owner":"apphp","description":"DataGrid helpers for easy creating CRUD in Laravel Framework Applications","archived":false,"fork":false,"pushed_at":"2023-07-31T20:10:28.000Z","size":185,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T08:56:09.471Z","etag":null,"topics":["apphp","datagrid-helpers","filter-helpers","laravel","laravel-crud","laravel-package","laravel6","laravel6-package","pagination-helpers"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apphp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-20T21:48:14.000Z","updated_at":"2024-10-08T11:25:53.000Z","dependencies_parsed_at":"2024-09-14T18:28:17.000Z","dependency_job_id":"a4bea22b-481c-4277-bd01-6ba58d862b57","html_url":"https://github.com/apphp/laravel-datagrid","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apphp%2Flaravel-datagrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apphp%2Flaravel-datagrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apphp%2Flaravel-datagrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apphp%2Flaravel-datagrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apphp","download_url":"https://codeload.github.com/apphp/laravel-datagrid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238472027,"owners_count":19478147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apphp","datagrid-helpers","filter-helpers","laravel","laravel-crud","laravel-package","laravel6","laravel6-package","pagination-helpers"],"created_at":"2024-09-24T13:51:00.146Z","updated_at":"2025-10-27T09:31:28.997Z","avatar_url":"https://github.com/apphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)\n\n\n# DataGrid helpers for Laravel Framework Applications\n\nThis package helps to create DataGrid (CRUD) pages for Laravel 6+ framework applications.\n\n\n## Requirements\n\n* PHP \u003e=7.1\n* Laravel 6+\n* Bootstrap 3+\n\n\n## License\n\nThis project is released under the MIT License.   \nCopyright © 2020 [ApPHP](https://www.apphp.com/).\n\n\n## Installation\n\nBegin by pulling in the package through Composer.\n\n```bash\ncomposer require apphp/laravel-datagrid\n```\n\nNext, make sure you connected Bootstrap. You may either pull in the Bootstrap's CSS within your HTML or layout file, or write your own CSS \nclasses based on them. \n\n```html\n\u003clink rel=\"stylesheet\" href=\"//getbootstrap.com/docs/4.0/dist/css/bootstrap.min.css\"\u003e\n```\n\nIf you need to modify the datagrid files, you can run:\n\n```bash\nphp artisan vendor:publish --provider=\"Apphp\\DataGrid\\DataGridServiceProvider\"\n```\n\n## Usage in Controllers  \n\n### 1. Import classes\n```php \nuse Apphp\\DataGrid\\Pagination;\nuse Apphp\\DataGrid\\Filter;\n```\n\n### 2. Define filters and filter field types\n```php\n$filters      = [\n    'act' =\u003e ['type' =\u003e 'equals', 'value' =\u003e 'search'],\n    'email'    =\u003e ['title' =\u003e 'Email', 'type' =\u003e 'string', 'compareType' =\u003e '%like%', 'validation' =\u003e ['maxLength' =\u003e 150]],\n    'name'     =\u003e ['title' =\u003e 'Name', 'type' =\u003e 'string', 'compareType' =\u003e '%like%'],\n    'username' =\u003e ['title' =\u003e 'Username', 'type' =\u003e 'string', 'compareType' =\u003e '%like%'],\n    'user_id'  =\u003e ['title' =\u003e 'ID', 'type' =\u003e 'integer', 'compareType' =\u003e '=', 'validation' =\u003e ['max' =\u003e 10000000]],\n];\n```\n\nFollowing filter field types are available\n\n| Type                | Description                                                                |\n|---------------------|----------------------------------------------------------------------------|\n| `string`            | Any type of strings         \n| `integer` or `int`  | Numeric integer field (HTML type=\"number\" attribute is used)         \n| `set`               | Set of values (array)         \n| `date`              | The datetime fields\n\n\nEach filter field can include following attributes:\n\n| Attribute        | Type       | Description                                                                  \n|------------------|------------|-------------------------------------------------------------------\n| `title`          | String     | Specifies a title, that will be shown in the label of filter field         \n| `type`           | String     | Specifies a type of the filter field (see above)         \n| `compareType`    | String     | Specifies which type of comparison will be used: ex.: '=', '%like%', '!=' etc.         \n| `source`         | Array      | Specifies the source (array) to 'set' fields         \n| `validation`     | Array      | Specifies validation rules (array). Possible options: ['minLength'=\u003e2, 'maxLength'=\u003e10, 'min'=\u003e2, 'max'=\u003e100]           \n| `relation`       | String     | Specifies the relation between 2 models (One-to-One, One-to-Many), ex.: search in posts for users - relation=\"posts\"          \n| `relationXref`   | String     | Specifies the relation between 2 models (Many-to-Many), ex.: search in roles for users - relation=\"roles\"         \n| `htmlOptions`    | Array      | Specifies any possible HTML attribute for the field          \n| `disabled`       | Boolean    | Specifies whether the field is disabled or not (default - not)           \n  \n\n### 3. Handle filters and prepare SQL builder\n```php\n// $query = User::sortable()-\u003eorderByDesc('id');\n$query = User::orderByDesc('id');\n$request = request(); // or get it via function param, like foo(Request $request){...}\n$url = route('backend.users.submitRote');\n$cancelUrl = $url;\n$filters = [];\n\n$filter       = Filter::init($query, $request, $filters, $url, $cancelUrl, 'collapsed');\n$filter       = $filter::filter();\n$filterFields = $filter::getFilterFields();\n$query        = $filter::getQuery();\n```\n\n### 4. Sorting\n```php \n$sort      = $request-\u003eget('sort');\n$direction = $request-\u003eget('direction');\n```\n\n### 5. Pagination\n```php \n$pagination       = Pagination::init($query, 20, $sort, $direction, $filterFields)::paginate();\n$paginationFields = $pagination::getPaginationFields();\n$users            = $pagination::getRecords();\n```\n\n### 6. Rendering view\n```php\nreturn view('backend.users.mainView', compact('users', 'filterFields', 'paginationFields'));\n```\n\n\n## Usage in View files \n```html\n\u003cscript\u003e\n    {!! \\Apphp\\DataGrid\\Filter::renderJs() !!}\n\u003c/script\u003e\n\n@if(count($records))\n    {!! \\Apphp\\DataGrid\\Filter::renderFields() !!}\n    \n        \u003c!-- YOUR TABLE WITH RECORDS DATA --\u003e\n        @foreach ($records as $record)\n        \u003c!-- ... --\u003e\n        @endforeach\n        \u003c!-- YOUR TABLE WITH RECORDS DATA --\u003e\n\n    {!! \\Apphp\\DataGrid\\Pagination::renderLinks() !!}\n@else\n    {!! \\Apphp\\DataGrid\\Message::warning('Sorry, no records were found. Please adjust your search criteria and try again.') !!}\n@endif\n```\n\n\n## Configuration\n\nTo change default settings and enable some extra features you can export the config file:\n```bash\nphp artisan vendor:publish --tag=laravel-datagrid:config\n```\n\n\n## Localization\n\nTo change or add new translation files you can export the language files:\n```bash\nphp artisan vendor:publish --tag=laravel-datagrid:lang\n```\n\n\n## Customize Views \n\nTo change HTML template of the datagrid or use your own, publish view file and customize it to suit your needs.\n```bash\n$ php artisan vendor:publish --tag=laravel-datagrid:views\n```\nNow you should have a datagrid.php file in the config folder of your application. If you need to force to re-publish the config file to use `--force`.\n\n\n## Testing \n\nTo rum unit testing simply do following:\n```bash\n./vendor/bin/phpunit vendor\\\\apphp\\\\laravel-datagrid\\\\tests\\\\TestDataGridMessage.php\n```\n\nor your may add additional section to your composer.json file:\n```json\n\"scripts\": {\n    \"tests\": \"phpunit --colors=always\",\n    \"test\": \"phpunit --colors=always --filter\",\n}\n```\n\nand then rum unit following command:\n```bash\ncomposer tests vendor\\\\apphp\\\\laravel-datagrid\\\\tests\\\\TestDataGridMessage.php\ncomposer tests vendor\\\\apphp\\\\laravel-datagrid\\\\tests\\\\TestDataGridPagination.php\ncomposer tests vendor\\\\apphp\\\\laravel-datagrid\\\\tests\\\\TestDataGridFilter.php\n ```\n\nand so on...\n\n## Examples\n\n### Controller code (full example)\n```php\npublic function index(Request $request)\n{\n    // Additional data\n    $roles    = Role::rolesList();\n    $statuses = User::statusesList();\n    $actives  = [0 =\u003e 'Not Active', 1 =\u003e 'Active'];\n\n    // Define filters and filter field types\n    $filters      = [\n        'act' =\u003e ['type' =\u003e 'equals', 'value' =\u003e 'search'],\n    \n        'email'    =\u003e ['title' =\u003e 'Email', 'type' =\u003e 'string', 'compareType' =\u003e '%like%', 'validation' =\u003e ['maxLength' =\u003e 150]],\n        'name'     =\u003e ['title' =\u003e 'Name', 'type' =\u003e 'string', 'compareType' =\u003e '%like%'],\n        'username' =\u003e ['title' =\u003e 'Username', 'type' =\u003e 'string', 'compareType' =\u003e '%like%'],\n        'user_id'  =\u003e ['title' =\u003e 'ID', 'type' =\u003e 'integer', 'compareType' =\u003e '=', 'validation' =\u003e ['max' =\u003e 10000000]],\n    \n        'role'       =\u003e ['title' =\u003e 'Role', 'type' =\u003e 'user_role', 'compareType' =\u003e '', 'source' =\u003e $roles],\n        'status'     =\u003e ['title' =\u003e 'Status', 'type' =\u003e 'user_status', 'compareType' =\u003e '', 'source' =\u003e $statuses],\n        'active'     =\u003e ['title' =\u003e 'Active', 'type' =\u003e 'user_active', 'compareType' =\u003e '', 'source' =\u003e $actives],\n    \n        'created_at'    =\u003e ['title' =\u003e 'Created At', 'type' =\u003e 'date', 'compareType' =\u003e 'like%'],\n        'last_logged_at' =\u003e ['title' =\u003e 'Last Login', 'type' =\u003e 'date', 'compareType' =\u003e 'like%'],\n    ];\n    \n    $query = User::orderByDesc('id');\n    \n    // Handle filters and prepare SQL query\n    $filter       = Filter::init($query, $request, $filters, route('users.list'), route('users.list'), 'collapsed');\n    $filter       = $filter::filter();\n    $filterFields = $filter::getFilterFields();\n    $query        = $filter::getQuery();\n    \n    // Sorting\n    $sort      = $request-\u003eget('sort');\n    $direction = $request-\u003eget('direction');\n    \n    // Pagination\n    $pagination       = Pagination::init($query, 20, $sort, $direction, $filterFields)::paginate();\n    $paginationFields = $pagination::getPaginationFields();\n    $users            = $pagination::getRecords();\n    \n    return view('users.list', compact('users', 'filterFields', 'paginationFields'));\n}\n```\n\n### Sorting \n\nIf you use some kind of packages for column sorting, like `kyslik/column-sortable`, you have to change usage of Model to following:\nWithout sorting\n```php\n$query = User::orderByDesc('id');\n```\nWith column sorting\n```php\n$query = User::sortable()-\u003eorderByDesc('id');\n```\n\n### Table content rendering\n\nYou have 2 way to render table content.\nThe first is to write creating table manually in view file. Look on example below:\n\n```html\n\u003cdiv class=\"table-responsive\"\u003e\n    \u003ctable class=\"table table-bordered table-striped\"\u003e\n    \u003cthead\u003e\n    \u003ctr\u003e\n        \u003cth class=\"text-right\" width=\"60px\"\u003e@sortablelink('user_id', 'ID')\u003c/th\u003e\n        ...\n    \u003c/tr\u003e\n    \u003c/thead\u003e\n    \u003ctbody\u003e\n        @foreach ($users as $user)\n            \u003ctr\u003e\n                \u003ctd class=\"text-right\"\u003e{{ $user-\u003euser_id }}\u003c/td\u003e\n                ...\n            \u003c/tr\u003e\n        @endforeach\n    \u003c/tbody\u003e\n    \u003c/table\u003e\n\u003c/div\u003e\n``` \n\nThe second way is to use \u003ccode\u003eGridView\u003c/code\u003e helper. Look on example below:\n```php\n// GridView - initialized in Controller\n$gridView = GridView::init($records);\n\nreturn view('backend.users', compact(..., 'gridView'));\n```\n\n```html\n{{-- Render table content --}}\n{!!\n    $gridView::renderTable([\n        'user_id'           =\u003e ['title' =\u003e 'ID', 'width'=\u003e'60px', 'headClass'=\u003e'text-right', 'class'=\u003e'text-right', 'sortable'=\u003etrue, 'callback'=\u003enull],\n        'username'          =\u003e ['title' =\u003e 'Username', 'width'=\u003e'', 'headClass'=\u003e'text-left', 'class'=\u003e'', 'sortable'=\u003etrue],\n        'name'              =\u003e ['title' =\u003e 'Name', 'width'=\u003e'', 'headClass'=\u003e'text-left', 'class'=\u003e'', 'sortable'=\u003etrue],\n        'email'             =\u003e ['title' =\u003e 'Email', 'width'=\u003e'', 'headClass'=\u003e'text-left', 'class'=\u003e'text-truncate px-2', 'sortable'=\u003etrue],\n        'created_at'        =\u003e ['title' =\u003e 'Created At', 'width'=\u003e'160px', 'headClass'=\u003e'text-center', 'class'=\u003e'text-center px-1', 'sortable'=\u003etrue],\n        'last_login_at'     =\u003e ['title' =\u003e 'Last Login', 'width'=\u003e'160px', 'headClass'=\u003e'text-center', 'class'=\u003e'text-center px-1', 'sortable'=\u003efalse],\n    ])\n!!}\n```\n\nYou may also use a `callback` attribute to customize values of the specific field. This attribute accepts a function, link to function or a closure. \nBelow you may find few examples to get a feel:\n\nShow specific badge if user has verified \n```php\n'callback'=\u003efunction($user){ return $user-\u003eisVerified() ? '\u003cspan class=\"badge badge-primary\"\u003eVerified\u003c/span\u003e' : '\u003cspan class=\"badge badge-secondary\"\u003eWaiting\u003c/span\u003e'; }\n```\n\nShow a list of user roles, get array of roles via `$roles` parameter \n```php\n'callback'=\u003efunction($user) use ($roles){ $output = ''; if(!count($user-\u003eroles)) $output .= '\u003cspan class=\"badge badge-light\"\u003eUser\u003c/span\u003e'; foreach($user-\u003eroles as $role) { $output .= '\u003cspan class=\"badge badge-info\"\u003e'.$roles[$role-\u003ename].'\u003c/span\u003e '; } return $output; }\n```\n\nShow user's avatar with a link to edit \n```php\n'callback'=\u003efunction($user){ return '\u003cimg src=\"'.$user-\u003eavatar.'\" alt=\"avatar\" /\u003e \u003ca href=\"'.route('users.show', $user).'\" title=\"Click to edit\"\u003e'.$user-\u003eusername.'\u003c/a\u003e'; }\n```\n\n\n### Collapsed filter\n\n![Collapsed filter](https://raw.githubusercontent.com/apphp/laravel-datagrid/master/images/filter-collapsed.png)\n\n### Expanded filter\n![Expanded filter](https://raw.githubusercontent.com/apphp/laravel-datagrid/master/images/filter-expanded.png)\n\n### Pagination\n![Pagination](https://raw.githubusercontent.com/apphp/laravel-datagrid/master/images/paganation.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapphp%2Flaravel-datagrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapphp%2Flaravel-datagrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapphp%2Flaravel-datagrid/lists"}