Create Query

Template

<?php ș

namespace App\Modules\Academic\Queries;

use App\Modules\Academic\Models\Student;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Spatie\QueryBuilder\QueryBuilder;
use Spatie\QueryBuilder\AllowedFilter;

class ListStudentsQuery
{
    /**
     * Get a paginated list of students with filters.
     *
     * @param int $perPage
     * @return LengthAwarePaginator
     */
    public function handle(int $perPage = 15): LengthAwarePaginator
    {
        return QueryBuilder::for(Student::class)
            ->allowedFilters([
                AllowedFilter::partial('name'),
                AllowedFilter::exact('status'),
                AllowedFilter::exact('campus_id'),
            ])
            ->allowedSorts(['created_at', 'name'])
            ->defaultSort('-created_at')
            ->paginate($perPage)
            ->withQueryString();
    }
}

Best Practices

• Use QueryBuilder: For filtering and sorting API/Web lists.
• No Side Effects: A query should never modify the database.
• Optimization: Use select(), with() (eager loading) to prevent N+1 issues.
• Authorization: Ensure the query respects scopes (e.g., currentCampus()).