Download the PHP package redsky-thirty/laravel-api-query-builder without Composer

Laravel API Query Builder

A lightweight and composable query builder for Laravel APIs, inspired by GraphQL flexibility.
Select only the fields and relations you want. Filter, sort, paginate — cleanly.

Current version: 1.0.10

Table of contents

• Features
• Installation
• Usage
  • Collection Mode
  • Single Resource Mode
  • Usage Without Executing a Query
• Always Fields
  • Priority Rules
• Sorting
  • Basic Usage
  • Defining Allowed Sorts
  • Default Sorts
• Resource example
• Nested Relation Helpers
  • Usage
  • Behavior
  • Signature
• Demo
  • Getting started
  • Customizing the Demo
• Example URLs
• Requirements
• License

Features

• ✅ Dynamic field selection (fields[users]=name,email)
• ✅ Relation loading with nested control (relations=posts.comments)
• ✅ Filtering (where[status]=active)
• ✅ Logical AND / OR filtering (where[name]=john|doe)
• ✅ Sorting (orderby=-created_at)
• ✅ Strict mode for validation

Installation

Usage

Collection Mode

This mode is used to retrieve multiple results from the database. It can automatically decide between returning a full collection or a paginated response based on the presence of the per_page parameter.

Single Resource Mode

This mode allows you to build the query manually and return a single model instance (e.g., User::find(...)). Useful for retrieving one resource with relation and field selection logic applied.

Usage Without Executing a Query

You can initialize field and relation selection logic without executing any database queries using the prepareWithoutQuery() method. This is particularly useful when preparing resource responses or resolving metadata without needing to fetch actual records.

This method parses the requested fields from the URL and stores them in the internal FieldRegistry, allowing your resources to behave consistently with the API expectations — all without triggering any Eloquent or SQL operations.

Always Fields

Sometimes, certain fields are required internally even if the client hasn't explicitly requested them. For example, foreign keys used to link relationships.

To support this, the alwaysFields() method allows you to define fields that should always be included in the response, even if they are not present in the fields[...] parameters or in the defaultFields() fallback.

These fields will be automatically merged into the requested or default field set before the resource is rendered.

⚠️ Priority Rules

• alwaysFields are not filtered by allowedFields
• They are injected unconditionally
• Useful for internal fields like foreign keys or polymorphic links

Sorting

The orderby parameter allows you to dynamically control the sort order of your API results.

Basic Usage

You can specify one or multiple fields to sort by.
By default, the sort order is ascending unless you prefix the field with a minus (-) for descending order.

Examples

Defining Allowed Sorts

To restrict which fields can be used for sorting, you can use the allowedSorts() method:

If a user tries to sort by a field not in the allowed list, the query builder will ignore it (or throw an exception if strict mode is enabled).

Default Sorts

You can define default sorts using the defaultSorts() method.
This will be applied automatically if no orderby parameter is provided.

This ensures that your API always returns predictable results even when no explicit sorting is requested.

Resource example

Nested Relation Helpers

Sometimes you may want to include data in a Resource only if a nested relation has been loaded.
Laravel provides the whenLoaded() method but it only works with direct relations.

To solve this, the package includes the HasNestedWhenLoaded trait.

Usage

Behavior

• If the full relation chain (user.profile) is loaded → the callback is executed.
• If any intermediate relation is missing → the default value (null) is returned.
• Supports unlimited depth (e.g. user.profile.address.country).

Signature

• $relation: Nested relation using dot notation (parent.child.grandchild).
• $callback: Function executed if all relations in the chain are loaded.
• $default: Value returned if the relation is not loaded (defaults to null).

Demo

This package includes a demo Laravel application for local testing and exploration.

🚀 Getting started

To launch the demo project:

Then open your browser at http://localhost:8000/api/users.

🔧 Customizing the Demo

The logic used to test the API query builder is defined inside:

You can modify or extend this file freely to experiment with:

• Custom endpoints
• Different models and relationships
• Field selection, filtering, sorting, and nested relations

This allows you to test the package without needing to copy files into a separate Laravel project.

Note: The demo/ folder is for local use only and should not be required in production.

Example URLs

1. Select default fields with relations

2. Select specific fields

3. Load relations and limit fields

4. Filter with equals, OR and AND

5. Filter with operators

6. Search (LIKE)

7. Sort results

8. Pagination

9. "Single Resource Mode" and "Without Executing a Query"

All URL parameters related to field selection demonstrated above can also be used with single-resource endpoints like /api/users/{id} or /api/users/random.

This works especially well when using the prepareWithoutQuery() method, which allows parsing and validation of requested fields and relations without performing any database query. This ensures consistent response shaping even when loading a single resource outside of the query builder's automatic mode.

All URL examples provided above are fully replicable with the Single Resource usage (e.g. via /api/users/{id}). This ensures a consistent API experience whether you're fetching a list of resources or a single one.

In contrast, when using the prepareWithoutQuery() method (query-less mode), only field selection logic (i.e. the fields[...] parameters) is parsed and validated. This is useful for shaping responses or metadata without performing any database access, but it does not apply filters, sorting, or relation loading.

In contrast, when using the prepareWithoutQuery() method (query-less mode), only field selection logic (i.e. the fields[...] parameters) is parsed and validated. This is useful for shaping responses or metadata without performing any database access — such as in the demo endpoints /api/users/random — but it does not apply filters, sorting, or relation loading.

Requirements

• PHP 8.3+
• Laravel 12+

License

MIT © Redsky-Thirty