README

A structured query parser and Eloquent/Scout integration toolkit for Laravel APIs

The iWasteNot API Query Helper provides a consistent way to transform HTTP query parameters into robust Eloquent (or Laravel Scout) queries.
It standardizes filtering, sorting, field selection, and relationship inclusion for JSON APIs without requiring repetitive controller code.

🧱 Core Concept

Write API endpoints like:

GET /api/items?_with=photos&_fields=id,title,price&_sort=-created_at&price-gte=100&status-eq=active

and get this automatically:

Item::with(['photos'])
    ->select(['id', 'title', 'price'])
    ->where('price', '>=', 100)
    ->where('status', '=', 'active')
    ->orderBy('created_at', 'desc')
    ->get();

All query parsing, validation, and recursion are handled internally.

✅ Compatibility

Component	Supported versions
PHP	>= 7.4
Laravel / Illuminate	8.x, 9.x, 10.x, 11.x, 12.x

Notes:

When PHP is 7.4, only Laravel/Illuminate 8.x is supported.

⚡ Quick Start

composer install --no-interaction --prefer-dist
vendor/bin/phpunit

🚀 Installation

composer require iwastenot/laravel-api-query-helper

Then import the helper where you build your API queries:

use IWasteNot\ApiQueryHelper\Services\ApiQueryHelper;

class ItemController extends Controller
{
    public function index(Request $request, ApiQueryHelper $api)
    {
        $query = Item::query();

        $results = $api->indexHelper($query, $request->all())
            ->paginate();

        return new IndexCollection($results);
    }
}

📚 Documentation

docs/tutorials/getting-started.md — walkthrough from model to request
docs/how-to/filters.md — filter patterns + suffix list
docs/how-to/relations.md — nested _with, _fields, _sort, filters
docs/how-to/scout.md — Scout search and _q
docs/ApiQueryHelper.md — reference for helper methods
docs/ApiModel.md — reference for model helpers
docs/glossary.md — glossary of query terms
docs/faq.md — common questions and troubleshooting
docs/migration-notes.md — behavior changes between releases
docs/developer-guide.md — contributor setup notes

⚙️ Supported Parameters

Parameter	Type	Description
`_with`	comma-separated list	Eager-load relationships (`with()`)
`_fields`	comma-separated list	Restrict selected columns
`_sort`	comma-separated list	Sort fields, prefix with `-` for descending; dotted paths (`category-name`) sort by related columns
`_q`	string	Model-directed search across the model's `$searchable` fields
`_or[N][...]`	bracketed groups	Or-groups: entries or-combine, groups and-combine with everything else
all others	filters	Translated into `where*()` clauses based on suffix

🔎 Filter Syntax

Filters are derived from all parameters except _with, _fields, _sort, _q, and _or. Keys that start with _ are ignored by the filter parser.

Example	Effect	Method
`status-eq=active`	`status = 'active'`	`where()`
`price-gte=100`	`price >= 100`	`where()`
`deleted-null`	`deleted IS NULL`	`whereNull()`
`deleted-not-null`	`deleted IS NOT NULL`	`whereNotNull()`
`id-in=1,2,3`	`id IN (1,2,3)`	`whereIn()`
`role-not-in=admin,staff`	`role NOT IN (...)`	`whereNotIn()`
`created-between=2024-01-01,2024-12-31`	Date range	`whereBetween()`
`gte=price,100`	`price >= 100`	`where()`
`status=active`	`status = 'active'`	`where()`
`title-lk=%a%\\|%b%`	`title LIKE '%a%' OR title LIKE '%b%'`	grouped `orWhere()`
`category-name-lk=%x%`	parent rows with a matching category	`whereHas()`
`_or[0][a-lk]=%x%&_or[0][b-lk]=%y%`	`(a LIKE '%x%' OR b LIKE '%y%')`	nested `where()`

Supported suffixes

The helper supports these suffixes by default:

lk, like => where ... like
not-lk, not-like => where ... not like
gte => where ... >=
lte => where ... <=
gt => where ... >
lt => where ... <
eq => where ... =
not, not-eq => where ... !=
null => whereNull
not-null => whereNotNull
in => whereIn
not-in => whereNotIn
between => whereBetween
not-between => whereNotBetween
date => whereDate
year => whereYear
month => whereMonth
day => whereDay
time => whereTime
column => whereColumn

For null / not-null, the value list is ignored and no parameters are passed to the where method.

Suffixes and aliases are normalized via a configurable $suffixes map. In the suffix-as-key form (for example, gte=price,100), the first value is the field name and the remaining values are parameters for the where clause. In the suffix-in-key form, hyphens in the field portion are interpreted as dots for nested relations (for example, photos-filename-like=image targets photos.filename).

🧮 Eloquent Integration

Models intended for API use should extend the provided ApiModel class.

Example

use IWasteNot\ApiQueryHelper\Models\ApiModel;

class Item extends ApiModel
{
    protected $fillable = ['title', 'price', 'status'];
    protected $joinable = ['photos', 'tags'];
    protected $details = ['description', 'notes'];

    public function photos() { return $this->hasMany(Photo::class); }
    public function tags() { return $this->belongsToMany(Tag::class); }
}

This gives ApiQueryHelper introspection capabilities through:

getJoinable() — whitelist of relationships allowed in _with
getKeys() — all known safe fields
getIndexKeys() — indexable, visible subset
getIndexAttributes() — filtered attributes for display

💡 Usage Examples

Basic filtering, sorting, and field selection

GET /api/items?_fields=id,title,price&_sort=-created_at&price-lte=100&status-eq=active

Item::select(['id','title','price'])
    ->where('price', '<=', 100)
    ->where('status', '=', 'active')
    ->orderBy('created_at', 'desc')
    ->get();

Eager loading and nested filtering

GET /api/items?_with=photos,tags&photos.filename-like=image

→ Loads related photos where the filename matches "image".

Nested relation fields and sorts

GET /api/items?_with=photos&photos._fields=id,filename&photos._sort=-created_at

→ Scopes _fields and _sort to the photos relation.

Full-text search with Laravel Scout

$results = $api->indexHelper(Item::class, ['_q' => 'hammer']);

When you call indexHelper() with a model class name, Scout mode is used only when the params are limited to _q, per_page, and offset. The helper does not apply pagination itself; those values are for your controller/paginator.

_q searches the fields that your Scout driver indexes for the model. Define them by overriding toSearchableArray() and reindex after changes.

Custom prefiltering in models

public function indexHelperEloquent($query, $joins, $fields, $sorts, $filters)
{
    $filters['status'][] = ['=', 'active'];
    return [$query, $joins, $fields, $sorts, $filters];
}

See docs/ApiQueryHelper.md for extension-point details.

Show helper for single models

$item = Item::findOrFail($id);
$item = $api->showHelper($item, request()->all());

→ Loads _with relations without altering the base query.

🧩 Internal Structure

File	Role
`ApiQueryHelper.php`	Main query parser and orchestrator
`Arr.php`	Array filtering utilities for dotted keys
`ApiModel.php`	Base model with introspection hooks
`IndexCollection.php`	(optional) Resource wrapper for paginated results

🧪 Testing

vendor/bin/phpunit

⚠️ Limitations

Scout filters are not whitelisted via getKeys().
Pagination is controlled by your controller (the helper does not paginate).

🩹 Troubleshooting

If Scout returns no results, confirm the driver is configured and the model index is built/rebuilt.
If filters are ignored, ensure the field is present in getKeys().
If nested filters do nothing, confirm the parent relation is in _with.

Changelog

See CHANGELOG.md for release notes and historical changes.

📄 License

MIT. See LICENSE.

iwastenot / laravel-api-query-helper

Maintainers

Package info

Statistics

Security