Download the PHP package rawnoq/laravel-query-api without Composer

Laravel Query API

A powerful and elegant Laravel package that brings GraphQL-like flexibility to your REST APIs. Built on top of Spatie Laravel Query Builder, it provides a fluent API for managing complex queries with ease.

Features

• ✅ Sorting - Sort results by multiple fields with ascending/descending order
• ✅ Default Sorting - Define default sorting behavior
• ✅ Sparse Fieldsets - Request only the fields you need
• ✅ Virtual Fields - Support for computed/accessor fields that aren't database columns
• ✅ Filters - Support for exact, partial, scope, callback, operator, exclusion, and custom filters
• ✅ Includes (Relationships) - Load relationships with count, exists, and custom includes
• ✅ Pagination - Built-in pagination support
• ✅ Config Classes - Organize query configurations in dedicated classes
• ✅ Fluent API - Beautiful and intuitive API with method chaining
• ✅ HMVC Support - Full compatibility with rawnoq/laravel-hmvc package
• ✅ Artisan Command - Generate QueryAPI config classes easily
• ✅ Helper Methods - Built-in helpers for checking requested fields and includes in Resources
• ✅ Security - Whitelist-based access control for fields, filters, and relationships

Requirements

• PHP >= 8.2
• Laravel >= 12.0
• Spatie Laravel Query Builder >= 6.0

Installation

Install the package via Composer:

The package will automatically register itself via Laravel's package discovery.

Quick Start

Generate QueryAPI Config Class

The easiest way to get started is to generate a QueryAPI config class using the Artisan command:

This will create a file at app/QueryAPI/UserQueryAPI.php (or modules/{Module}/App/QueryAPI/ for HMVC) with all the basic methods stubbed out.

Basic Usage with Helper Function

Using Config Classes (Recommended)

Create a config class to organize your query settings:

Use the config class in your controller:

Query Parameters

Sorting

Fields (Sparse Fieldsets)

Filters

Partial Filter (LIKE):

Exact Filter:

Operator Filters:

Scope Filters:

Exclusion Filters:

Includes (Relationships)

Pagination

Flexible Pagination Methods:

Complete Example

Available Methods

Core Methods

Filter Types

Exact Filter

Partial Filter (LIKE %value%)

Begins With Filter (LIKE value%)

Ends With Filter (LIKE %value)

Scope Filter

Callback Filter

Operator Filter

Trashed Filter (Soft Deletes)

Exclusion Filters

Include Types

Relationship Include

Count Include

Exists Include

Callback Include

Custom Include

Pagination Configuration

You can configure pagination defaults and limits per model:

Usage:

Advanced Usage

Using with Eloquent Query

Manual Configuration

Using Facade

Virtual Fields

Virtual fields are computed fields or accessors that aren't actual database columns. They can be requested in API calls but won't cause SQL errors.

Defining Virtual Fields

Using in Resources

Helper Methods

The package provides helper methods for checking requested fields and includes:

Performance

The package includes several performance optimizations:

• Model Table Caching: Table names are cached to avoid repeated model instantiation
• Efficient Field Parsing: Optimized parsing of field formats
• Lazy Loading: Relationships are only loaded when explicitly requested

To clear the model table cache (useful for testing):

Security

The package implements a whitelist-based security model:

1. Fields - Only explicitly allowed fields can be selected
2. Virtual Fields - Computed fields that are validated but not queried from database
3. Filters - Only explicitly allowed filters can be applied
4. Includes - Only explicitly allowed relationships can be loaded
5. Sorts - Only explicitly allowed fields can be sorted

Any unauthorized request will be silently ignored or throw an exception based on Spatie Query Builder configuration.

Artisan Commands

make:query-api

Generate a new QueryAPI configuration class:

Arguments:

• name - The name of the QueryAPI config class (e.g., UserQueryAPI)

Options:

• --model, -m - The model that this QueryAPI config is for
• --module - The module that this QueryAPI config belongs to (for HMVC structure)
• --force, -f - Create the class even if it already exists

Examples:

Publishing Stubs

You can publish the command stub for customization:

This will copy the stub file to stubs/query-api.stub in your project root where you can customize it.

Advanced Examples

Edge Cases

Handling Empty Results:

Custom Query with Filters:

Multiple Field Formats:

Virtual Fields with Nested Resources:

Complex Filtering:

Troubleshooting

Common Issues

Issue: "Requested field(s) are not allowed"

Issue: Virtual field causing SQL errors

Issue: Includes not loading

Issue: Model class not found

Issue: Performance with large datasets

Issue: Filter not working

Testing

Changelog

Please see CHANGELOG for more information on recent changes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security Vulnerabilities

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Rawnoq
• Spatie for the amazing Laravel Query Builder
• All contributors

License

The MIT License (MIT). Please see License File for more information.