README

Build powerful, dynamic API queries from URL parameters.
Let your API consumers select fields, filter, sort, group, paginate, and compute statistics — all from a single query string.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage Overview
  • Dynamic Fields
  • Dynamic Filtering
  • Dynamic Sorting
  • Dynamic Grouping
  • Dynamic Statistics
  • Dynamic Pagination
• All-in-One Scopes
• Configuration
• Detailed Documentation
• Security
• Testing
• License

Features

Requirements

• PHP >= 8.0
• Laravel 8.x / 9.x / 10.x / 11.x

Installation

composer require yassinedabbous/laravel-dynamic-query

Publish the configuration file (optional):

php artisan vendor:publish --tag=dynamic-query-config

The service provider is auto-discovered by Laravel.

Quick Start

1. Add the trait to your model

use YassineDabbous\DynamicQuery\HasDynamicQuery;

class Product extends Model
{
    use HasDynamicQuery;

    public function dynamicColumns(): array
    {
        return ['id', 'name', 'price', 'category_id', 'created_at'];
    }

    public function dynamicFilters(): array
    {
        return [
            'name'        => ['=', 'like%'],
            'price'       => ['=', '>', '<', '>=', '<=', 'between'],
            'category_id' => ['=', 'in'],
            'created_at'  => null, // all operators
        ];
    }

    public function dynamicSorts(): array
    {
        return ['id', 'name', 'price', 'created_at'];
    }
}

2. Use it in your controller

class ProductController extends Controller
{
    public function index()
    {
        // All-in-one: select, filter, sort, group, paginate, append
        return Product::dynamicAPI();

        // Or step-by-step:
        return Product::dynamicSelect()
                      ->dynamicFilter()
                      ->dynamicSort()
                      ->dynamicPaginate();
    }
}

3. Call your API

GET /api/products?_fields=id,name,price&name=Widget&_sort=-price&per_page=10

Response includes only id, name, price — filtered by name, sorted by price descending, 10 per page.

Usage Overview

Dynamic Fields

Select specific columns, relations, and nested relation fields:

GET /api/products?_fields=id,name,category:id|name

Declare what's available on your model:

public function dynamicColumns(): array {
    return ['id', 'name', 'price', 'category_id'];
}

public function dynamicRelations(): array {
    return [
        'category' => 'category_id',       // depends on category_id column
        'reviews'  => null,                 // no column dependency
    ];
}

public function dynamicAppends(): array {
    return [
        'full_name'   => ['first_name', 'last_name'],  // depends on columns
        'status_label' => 'status',                     // depends on status column
    ];
}

public function dynamicAggregates(): array {
    return [
        'reviews_count' => fn($q) => $q->withCount('reviews'),
    ];
}

📖 Full Fields Documentation →

Dynamic Filtering

Filter with any of 30+ operators:

GET /api/products?price=>=100&name=Widget&_operators[name]=like%

Negate with ! prefix:

GET /api/products?!category_id=5          # category_id != 5
GET /api/products?status=active&_logic=or  # OR logic across filters

Supports: =, !=, <, >, <=, >=, like, %like%, in, between, null, has, full_text, json_contains, json_overlaps, and more.

📖 Full Filtering Documentation →

Dynamic Sorting

Sort by one or more columns. Prefix with - for descending:

GET /api/products?_sort=price            # ASC
GET /api/products?_sort=-price,name      # price DESC, then name ASC
GET /api/products?_sort=user.name        # sort by related column (auto-join)

📖 Full Sorting Documentation →

Dynamic Grouping

Group results with optional date macros:

GET /api/products?_group=category_id
GET /api/orders?_group=created_at:month&_timezone=America/New_York
GET /api/orders?_group=created_at:year,status

Supported macros: year, month, day, hour.

📖 Full Grouping Documentation →

Dynamic Statistics

Compute metrics with grouping, transforms, comparisons, and caching:

GET /api/orders?_metric=sum:total&_group=created_at:month
GET /api/orders?_metric=avg:total&_transform=growth
GET /api/orders?_metric=count&_compare=previous_period&created_at[]=2024-01-01&created_at[]=2024-03-31

📖 Full Statistics Documentation →

Dynamic Pagination

GET /api/products?per_page=25            # 25 items per page
GET /api/products?_get_all=true          # return all (if enabled)
GET /api/products?_simple=true           # use simplePaginate

📖 Full Pagination Documentation →

All-in-One Scopes

// In a controller:
return Product::dynamicAPI();

// With explicit input (e.g. in a job or test):
return Product::dynamicAPI(['_fields' => 'id,name', '_sort' => '-price']);

Configuration

After publishing, edit config/dynamic-query.php:

return [
    'defaults' => [
        'per_page'      => 15,
        'max_per_page'  => 100,
        'allow_get_all' => false,
        'max_get_all'   => 1000,
        'cache_ttl'     => 600,
        'timezone'      => 'UTC',
    ],
    'settings' => [
        'enable_stats_cache' => false,
        'relation_guess'     => true,     // Auto-discover relations via Reflection
        'strict_filtering'   => true,     // Whitelist-only filtering
        'clean_response'     => true,     // Limit response to requested fields
    ],
    'params' => [
        'fields'  => '_fields',
        'sort'    => '_sort',
        'logic'   => '_logic',
        // ... and more
    ],
];

📖 Full Configuration Reference →

Detailed Documentation

Security

This package follows a whitelist-first security approach:

• Strict Filtering — Only filters defined in dynamicFilters() are applied (enabled by default).
• Column Whitelisting — Only columns listed in dynamicColumns() can be selected.
• SQL Sanitization — All dynamically generated aliases are sanitized via regex.
• Custom Metrics Safety — dynamicMetrics() values are developer-defined SQL, never user input.
• Pagination Limits — max_per_page and max_get_all prevent resource exhaustion.

Testing

composer test

License

The MIT License (MIT). See LICENSE for details.