README

LaraJS Query

Dynamic HTTP query parameter builder for Laravel Eloquent. Filter, sort, search, include relationships, select fields, and paginate using a functional query syntax.

Installation

composer require larajs/query:^2.0

Requirements: PHP 8.3+, Laravel 11/12/13

Quick Start

use App\Models\User;
use LaraJS\Query\LaraJSQuery;
use LaraJS\Query\DTO\{QueryParserAllowDTO, QueryParserRequestDTO};

class UserController
{
    use LaraJSQuery;

    public function index(Request $request)
    {
        return User::query()
            ->applyLaraJSQuery(
                QueryParserRequestDTO::fromArray($request->query()),
                QueryParserAllowDTO::fromArray([
                    'filter' => ['name', 'email'],
                    'include' => ['posts', 'roles'],
                    'sort' => ['name', 'created_at'],
                ])
            )
            ->get();
    }
}

Usage:

GET /api/users?filter=equals(name,'John')&sort=name&include[]=posts&pagination[limit]=10

Filtering

Filter with functional IBM-style syntax. All filters support relationship variants (e.g., equalsRelation, greaterThanRelation).

Sorting

Sort by single/multiple columns, including relationships via BelongsToThrough.

Searching

LIKE-based search across columns and relationships.

Including Relationships

Eager load relationships with nested support, aggregates, and filtering.

Supported aggregates: count, exists, sum, min, max, avg

Selecting Fields

Project specific columns via select parameter.

?select=id,name,email

Date Filtering

Filter by date ranges. Auto-calculates startOfDay/endOfDay boundaries.

Pagination

Three pagination types with configurable limits (default 25, max 500).

Security: Allow-List Whitelisting

Control queryable fields for each endpoint. By default, nothing is exposed — explicitly whitelist what clients can query.

$allow = QueryParserAllowDTO::fromArray([
    ‘field’   => [‘id’, ‘name’, ‘email’],         // Projectable columns
    ‘filter’  => [‘name’, ‘email’, ‘status’],     // Filterable fields
    ‘sort’    => [‘name’, ‘created_at’],          // Sortable columns
    ‘include’ => [‘posts’, ‘roles’],              // Includable relations
    ‘search’  => [‘name’, ‘email’],               // Searchable fields
    ‘date’    => [‘created_at’],                  // Date-filterable fields
]);

Repository Pattern

Use repositories to separate business logic from HTTP concerns.

// Repository
class UserRepository extends ReadRepository
{
    public function __construct()
    {
        parent::__construct(new User(), 25, 500);
    }
}

// Controller
class UserController
{
    public function __construct(private UserRepository $users) {}

    public function index(Request $request)
    {
        return $this->users->findAll(
            QueryParserAllowDTO::fromArray([...])
        );
    }
}

See /docs/deployment-guide.md for complete repository patterns.

Documentation

• Official Docs — Full online documentation
• docs/project-overview-pdr.md — Project scope, requirements, architecture
• docs/system-architecture.md — Detailed request lifecycle, component interactions
• docs/codebase-summary.md — File structure, data flow, algorithms
• docs/code-standards.md — PHP 8.3 patterns, naming conventions, security
• docs/deployment-guide.md — Installation, configuration, usage examples
• docs/project-roadmap.md — v2.0.0 status, planned features, roadmap