Skip to content

Commit 8ac5b3f

Browse files
hamidrezarjhamidrezarj
committed
updated README
1 parent 47caebb commit 8ac5b3f

File tree

1 file changed

+124
-36
lines changed

1 file changed

+124
-36
lines changed

‎README.md‎

Lines changed: 124 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
# Laravel React Datatable
1+
# Laravel Datatable
22

3-
[![Latest Version on Packagist](https://img.shields.io/packagist/v/hamidrrj/laravel-datatable.svg?style=flat-square)](https://packagist.org/packages/hamidrrj/laravel-datatable)
4-
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/hamidrrj/laravel-datatable/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/hamidrrj/laravel-datatable/actions?query=workflow%3Arun-tests+branch%3Amain)
5-
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/hamidrrj/laravel-datatable/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/hamidrrj/laravel-datatable/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
6-
[![Total Downloads](https://img.shields.io/packagist/dt/hamidrrj/laravel-datatable.svg?style=flat-square)](https://packagist.org/packages/hamidrrj/laravel-datatable)
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/hamidrezarj/laravel-datatable.svg?style=flat-square)](https://packagist.org/packages/hamidrezarj/laravel-datatable)
4+
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/hamidrezarj/laravel-datatable/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/hamidrezarj/laravel-datatable/actions?query=workflow%3Arun-tests+branch%3Amain)
5+
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/hamidrezarj/laravel-datatable/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/hamidrezarj/laravel-datatable/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
6+
[![Total Downloads](https://img.shields.io/packagist/dt/hamidrezarj/laravel-datatable.svg?style=flat-square)](https://packagist.org/packages/hamidrezarj/laravel-datatable)
77

8-
This package is implemented for dealing with Material React Table queries.
9-
It contains various search logics for different datatypes (numeric, text, date):
10-
1. Contains
11-
2. Between
12-
3. LessThan
13-
4. GreaterThan
14-
5. Equals
15-
6. NotEquals
8+
Laravel Datatable is a package designed to handle server-side logic for datatables in Laravel applications. <br>
169

17-
You can add your own search logic and datatype with ease :)
10+
## Key Features
11+
12+
- Standalone server-side solution for table-like data handling
13+
- Compatible with various frontend table libraries (e.g., [Material React Table](https://www.material-react-table.com/))
14+
- Support for multiple search logics (contains, equals, greater than, etc.) across different data types (numeric, text, date)
15+
- Fine-grained control over searchable, sortable, and visible fields
16+
- Ability to search through model relationships
17+
- Customizable search logic (coming soon!)
1818

1919
## Installation
2020

@@ -24,62 +24,150 @@ You can install the package via composer:
2424
composer require hamidrrj/laravel-datatable
2525
```
2626

27-
You can publish and run the migrations with:
27+
After installation, publish the package's service provider using one of the following methods:
28+
29+
#### Option 1: Automatic Installation (Recommended)
30+
Run the following Artisan command:
2831

2932
```bash
30-
php artisan vendor:publish --tag="laravel-datatable-migrations"
31-
php artisan migrate
33+
php artisan datatable:install
3234
```
3335

34-
You can publish the config file with:
36+
#### Option 2: Manual Installation
37+
Publish the provider manually:
3538

3639
```bash
37-
php artisan vendor:publish --tag="laravel-datatable-config"
40+
php artisan vendor:publish --tag="datatable-provider"
3841
```
3942

40-
This is the contents of the published config file:
43+
Then, add the following line to the providers array in `config/app.php`:
4144

42-
```php
45+
```bash
4346
return [
47+
// ...
48+
'providers' => ServiceProvider::defaultProviders()->merge([
49+
// ...
50+
App\Providers\DatatableServiceProvider::class,
51+
// ...
52+
])->toArray(),
53+
// ...
4454
];
4555
```
4656

47-
Optionally, you can publish the views using
57+
## Usage
4858

49-
```bash
50-
php artisan vendor:publish --tag="laravel-datatable-views"
59+
### Basic Usage
60+
61+
Here's a simple example of requesting a chunk of 10 users starting from the 11th record (i.e., page 2 of the datatable):
62+
63+
```php
64+
use \HamidRrj\LaravelDatatable\Facades\DatatableFacade;
65+
66+
$userModel = new User();
67+
68+
$requestParameters = [
69+
'start' => 10,
70+
'size' => 10,
71+
'filters' => [],
72+
'sorting' => []
73+
];
74+
75+
$data = DatatableFacade::run(
76+
$userModel,
77+
$requestParameters
78+
);
5179
```
5280

53-
## Usage
81+
### Using Query Builder
82+
You can use a query builder instance instead of a model instance:
83+
```php
84+
$query = User::query()->where('username', '!=', 'admin');
5485

86+
$data = DatatableFacade::run(
87+
$query,
88+
$requestParameters
89+
);
90+
```
91+
92+
### Advanced Filtering and Sorting
93+
Here's an example of filtering users whose usernames contain 'sth', sorted by creation date in descending order:
94+
```php
95+
$requestParameters = [
96+
'start' => 10,
97+
'size' => 10,
98+
'filters' => [
99+
[
100+
'id' => 'username',
101+
'value' => 'sth',
102+
'fn' => 'contains',
103+
'datatype' => 'text'
104+
]
105+
],
106+
'sorting' => [
107+
[
108+
'id' => 'created_at',
109+
'desc' => true,
110+
]
111+
]
112+
];
113+
114+
$allowedFilters = ['username'];
115+
$allowedSortings = ['created_at'];
116+
117+
$data = DatatableFacade::run(
118+
$query,
119+
$requestParameters,
120+
$allowedFilters,
121+
$allowedSortings
122+
);
123+
```
124+
**Note**: Ensure that columns used for filtering and sorting are included in the `$allowedFilters` and `$allowedSortings` arrays to avoid `InvalidFilterException` and `InvalidSortingException`.
125+
126+
### Method Parameters
127+
The `run` method of `DatatableFacade` accepts the following parameters:
128+
129+
1. `$mixed`: Model instance or query builder instance to perform queries on.
130+
2. `$requestParameters`: Contains parameters like `filter`, `sorting`, `size`, and `start` of required data.
131+
3. `$allowedFilters`: (Optional) Specifies columns users are allowed to filter on.
132+
4. `$allowedSortings`: (Optional) Specifies columns users are allowed to sort on.
133+
5. `$allowedSelects`: (Optional) Specifies which columns users can actually see.
134+
6. `$allowedRelations`: (Optional) Specifies which model relations users are allowed to filter on.
135+
136+
### Filter Array Structure
137+
Each filter in the `filters` array should have the following attributes:
138+
- `id`: Name of the column to filter on
139+
- `value`: Value of the filter
140+
- `fn`: Type of filter to apply (e.g., contains, between, equals, less than)
141+
- `datatype`: Type of column (e.g., text, numeric, date)
142+
143+
### Return Data Structure
144+
The `run` method returns an array with the following structure:
55145
```php
56-
$laravelDatatable = new HamidRrj\LaravelDatatable();
57-
echo $laravelDatatable->echoPhrase('Hello, HamidRrj!');
146+
[
147+
"data" => [
148+
// Array of matching records
149+
],
150+
"meta" => [
151+
"totalRowCount" => 10 // Total count of matching records
152+
]
153+
]
58154
```
59155

156+
60157
## Testing
61158

62159
```bash
63160
composer test
64161
```
65162

66163
## Changelog
67-
68164
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
69165

70166
## Contributing
71-
72167
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
73168

74-
## Security Vulnerabilities
75-
76-
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
77-
78169
## Credits
79-
80170
- [Hamidreza Ranjbarpour](https://github.com/hamidrezarj)
81-
- [All Contributors](../../contributors)
82171

83172
## License
84-
85173
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)