README

SmartFilter is a Laravel package designed to provide robust and flexible filtering capabilities for APIs. It allows developers to apply filters, sorting, and pagination to data retrieval seamlessly while returning structured JSON responses.

Installation

Require the package via Composer:

composer require pedrokeilerbatistarojo/smartfilter

Publish the configuration (optional):

php artisan vendor:publish --provider="Pedrokeilerbatistarojo\Smartfilter\SmartfilterServiceProvider"

Usage: Include the package in your controller or service to start applying filters.

Features

Apply filters with various operators (e.g., like, =, etc.).
Select specific columns to retrieve.
Include relationships for eager loading.
Sort results by any field.
Paginate results with customizable parameters.
Structured JSON responses with metadata.

Usage Example

Sample Request

GET /api/users?filters[0][0]=name&filters[0][1]=like&filters[0][2]=Owner&columns[]=id&columns[]=name&columns[]=email&includes[]=role&sortField=created_at&sortType=asc&itemsPerPage=8&currentPage=1

Query Params

filters:[["name", "like", "Owner", "and"],["email", "like","owner@example.com", "and"],["name", "like", "Owner", "and", "role"]]
columns:["id", "name", "email"]
includes:["role"]
sortField:created_at
sortType:asc
itemsPerPage:8
currentPage:1

Controller Example

use Pedrokeilerbatistarojo\Smartfilter\Services\FilterService;
use Pedrokeilerbatistarojo\Smartfilter\Helpers\ResponseHelper;
use Illuminate\Http\Request;
use App\Models\User;
use Exception;

class UserController extends Controller
{

    public function __construct(
        private readonly FilterService $filterService
    ){
    }

    /**
     * @throws Exception
     */
    public function __invoke(Request $request)
    {
       try {
          $response = $this->filterService->execute(User::class, $request->all());
          return ResponseHelper::sendResponse($response);
       }
       catch(Exception $ex){
          return ResponseHelper::sendError($ex->getMessage());
       } 
    }
}

Expected JSON Response

{
    "success": true,
    "message": "Search completed successfully",
    "errors": null,
    "payload": {
        "items": [
            {
                "id": 1,
                "name": "Owner",
                "email": "owner@example.com"
            },
            {
                "id": 2,
                "name": "Admin",
                "email": "admin@example.com"
            }
        ],
        "metadata": {
            "currentPage": 1,
            "lastPage": 5,
            "itemsPerPage": 8,
            "total": 40
        },
        "total": 40
    }
}

Testing

Run the test suite:
```
php artisan test
```

Example Test:

public function test_filter_with_filters(): void
{
    $filters = [
        ['name', 'like', 'Owner', 'and'],
        ['email', 'like', 'owner@example.com', 'and'],
        ['name', 'like', 'Owner', 'and', 'role']
    ];

    $columns = ['id', 'name', 'email'];
    $includes = ['role'];

    $params = [
        'filters' => $filters,
        'columns' => $columns,
        'includes' => $includes,
        'sortField' => 'created_at',
        'sortType' => 'asc',
        'itemsPerPage' => 8,
        'currentPage' => 1
    ];

    $queryString = http_build_query($params);
    $endpoint = "/api/users?{$queryString}";

    $response = $this->get($endpoint);
    $response->assertStatus(200);
    $response->assertJsonStructure([
        'success',
        'message',
        'errors',
        'payload' => [
            'items' => [
                '*' => [
                    'id',
                    'name',
                    'email'
                ]
            ],
            'metadata' => [
                'currentPage',
                'lastPage',
                'itemsPerPage',
                'total'
            ],
            'total'
        ]
    ]);
}

Contributing

Feel free to fork this repository and submit pull requests. Ensure that all tests pass and maintain code quality standards.

License

SmartFilter is open-source software licensed under the MIT License.

pedrokeilerbatistarojo / smartfilter

Maintainers

Details