Download the PHP package adonyarik/consistent-api without Composer

Consistent API

Laravel toolkit for lean, consistent REST APIs: modular route structure, CRUD controller, advanced filtering (including relations) and sorting (including relations), pagination, JSON/multipart middleware, debug responses, and PostgreSQL ENUM helpers.

Package: adonyarik/consistent-api Namespace: Adonyarik\ConsistentApi

Table of contents

• Consistent API
  • Table of contents
  • Installation
  • Configuration
  • config/consistentapi.php
  • config/pagination.php
  • config/filters.php
  • Modular structure
  • Rate limiting
  • Artisan commands
  • consistent:crud
  • consistent:rebuild
  • Models (CrudModel)
  • Disable pagination for a model
  • CRUD controller
  • Methods
  • Filtering
  • Simple columns
  • Nested operators
  • Filtering through relations
  • Validation of filter input
  • Sorting
  • Simple columns
  • Sorting through relations
  • Search request (BaseSearchRequest)
  • Startup validation of #[Filterable] / #[Sortable]
  • Pagination and responses
  • Middleware
  • Example usage
  • Debugger
  • Route macro development
  • PostgreSQL ENUM
  • DB macros
  • Blueprint macros
  • Extra traits
  • EnumHelpers
  • Credibility
  • Package structure
  • Quick start checklist
  • License

Installation

The service provider is registered via Laravel package discovery:

• Adonyarik\ConsistentApi\ConsistentApiProvider

It automatically boots:

• ModuleServiceProvider — module routes and the api rate limiter
• MacroServiceProvider — Route::development()
• PostgresEnumServiceProvider — PostgreSQL ENUM macros (migration/test context)

Publish the config files:

This creates:

• config/consistentapi.php
• config/pagination.php
• config/filters.php

Configuration

config/consistentapi.php

Example .env:

config/pagination.php

config/filters.php

An operator listed in operators must also be implemented in CanFilter::applyArrayFilter(), otherwise it is silently ignored at the trait level even if it passes validation.

Startup validation only runs in local / testing environments by default (see Startup validation); it never runs on every production request, so scanning the filesystem is not a performance concern there.

Modular structure

The package loads modules from app/{modules_folder} (default: app/Modules).

Example layout:

Module folders use the plural StudlyCase name of the model (Post → Posts, Company → Companies).

Each module Routes.php (and the optional root Routes.php) is loaded with:

• prefix from consistentapi.api_url_prefix (e.g. api)
• middleware from consistentapi.middlewares (e.g. api)

A folder named Middleware inside the modules directory is skipped.

If the modules directory does not exist, the provider does not fail — routes are simply not loaded.

Rate limiting

On boot, the package registers a limiter named api:

This may override your application's default api limiter. Adjust request_limit, or redefine the limiter in your AppServiceProvider / bootstrap/app.php if needed.

Artisan commands

Both commands use the consistent:{action} naming format.

consistent:crud

Creates a ready-to-extend module for the given model name:

Generated layout for Post:

• Model extends CrudModel with empty #[Fillable([])] / #[Hidden([])] / #[Filterable([])] / #[Sortable([])] declarations (Laravel 13+ for Eloquent attributes)
• Controller extends CrudController with index / show / store / update / destroy
• Search request extends BaseSearchRequest and points $model at the generated model, so relation/operator validation rules are built automatically
• Routes.php registers REST routes under the plural URI (posts) with {post} route-model binding
• Without --force, existing target files cause the command to fail

consistent:rebuild

Migrates a conventional Laravel layout into the same plural module structure:

• Models from app/Models
• Controllers from app/Http/Controllers (and app/Controllers)
• Requests from app/Http/Requests (and app/Requests)
• Resources from app/Http/Resources (and app/Resources)

Also:

• Rewrites namespaces and class references under app/, routes/, database/, and tests/
• Moves matching route statements from routes/api.php into each module's Routes.php

Example:

Post + PostController become App\Modules\Posts\Models\Post and App\Modules\Posts\Controllers\PostController.

Models (CrudModel)

Base API model:

Features:

• CanFilter and CanSort traits
• HasFactory with lookup for Database\Factories\{Model}Factory
• leftJoinOnce() — left join without duplicates
• getAllColumns() — table column listing

Disable pagination for a model

Implement the contract:

Then, with paginate=false (or 0), indexLogic returns the full list without pagination meta.

CRUD controller

Extend Adonyarik\ConsistentApi\Controllers\CrudController and set:

• $resourceClass — API Resource class
• $relationFunctions — relations for with / load (optional)

Methods

Models passed into these methods must extend CrudModel.

indexLogic validates filter/sort against the model's #[Filterable] / #[Sortable] declarations before the query is built. Any disallowed column, disallowed nested operator, or nesting on a column that doesn't support it returns a 422 with Laravel-style validation errors — the query is never executed with unverified input.

Filtering

Declare allowed columns on the model with #[Filterable]:

Simple columns

A plain string ('name') allows only scalar filtering, applied as LIKE '%value%' (ILIKE on PostgreSQL):

Nested operators

A column can be declared with an array of allowed operators, optionally paired with validation rules for that operator's value:

Supported operators (must also be enabled in config('filters.operators')):

A plain list of scalar values without operator keys is treated as in:

Attempting to nest a column that was declared as a plain string, or using an operator that isn't in its declared list, returns a 422.

Filtering through relations

Use RelationFilter for columns backed by a foreign key or a relationship, instead of the raw column:

Internally this runs whereHas($relation, ...) matching $column with LIKE/ILIKE (default) or = when operator: 'eq' is set — this works for any relation type (BelongsTo, HasMany, BelongsToMany, etc.) without duplicating rows. Nested operators (filter[user][eq]=...) on relation columns are not yet supported and return a 422.

Validation of filter input

BaseSearchRequest automatically builds validation rules from the model's #[Filterable]:

• Any operator not enabled in config('filters.operators') → 422.
• Any per-operator rules declared on the model (e.g. numeric, date, gte:filter.price.min) are applied to the corresponding filter.column.operator input.
• Columns declared as RelationFilter are excluded from value-rule generation (there is no scalar value shape to validate beyond the base type checks).

Sorting

Declare allowed columns on the model with #[Sortable]:

Simple columns

Sorting through relations

RelationSort inspects the relationship type and picks the right strategy automatically:

• BelongsTo / HasOne — a single related record, resolved with a leftJoinOnce() join, then ORDER BY {related_table}.{column}.
• BelongsToMany / HasMany — potentially multiple related records. To avoid row duplication from a JOIN, the values are aggregated into a single comma-separated string per parent row via a correlated subquery (STRING_AGG on PostgreSQL, GROUP_CONCAT on MySQL), and the main query orders by that subquery — no join on the outer query at all.

Sorting on a relation that isn't BelongsTo / HasOne / BelongsToMany / HasMany is silently ignored.

MySQL note: GROUP_CONCAT truncates at group_concat_max_len (1024 bytes by default). If a parent row can have many related values, consider raising this session/server variable.

Search request (BaseSearchRequest)

Setting $model lets BaseSearchRequest build the filter.* value-validation rules straight from that model's #[Filterable] declaration (see Validation of filter input). This is done automatically by the consistent:crud stub.

Base rules (always applied, regardless of $model):

Example request:

Behaviour at the controller level:

• Filtering: LIKE / ILIKE (PostgreSQL) on columns allowed by #[Filterable], or the operator/relation logic described above
• Sorting: orderBy on columns allowed by #[Sortable], or the relation logic described above
• Disallowed columns, disallowed nested operators, or filter/sort on a non-filterable/non-sortable model → 422 with Laravel-style validation errors

Simple array-based whitelisting (without the attribute) still works:

An empty array means filtering/sorting is disabled.

Startup validation of #[Filterable] / #[Sortable]

When config('filters.validate_on_boot') is true and the app is running in local or testing, ConsistentApiProvider::boot() scans every model under config('filters.model_paths') and eagerly checks:

• Every operator declared in a #[Filterable] column exists in config('filters.operators') → otherwise InvalidFilterableOperatorException.
• Every RelationFilter points to a method that exists on the model and actually returns an Eloquent Relation → otherwise InvalidRelationFilterException.

This catches typos (min used but not enabled in config, relation: 'usre', pointing a RelationFilter at a non-relation method) at boot time instead of on the first matching request.

model_paths supports a single * wildcard segment, which makes it work with both conventional (app/Models) and modular (app/Modules/*/Models) project layouts out of the box.

Disable this check entirely (e.g. to skip the filesystem scan) with:

Pagination and responses

PaginatedJsonResponse produces JSON like:

The items / meta keys are configurable in config/pagination.php.

Without pagination (contract + paginate=false):

Middleware

Aliases are registered automatically:

Example usage

Laravel 11+:

Or in routes:

Attach EnsureMultipartMiddleware only to upload endpoints: any non-POST request or missing multipart Content-Type returns 415.

Debugger

1. Set DEBUGGER_ENABLED=true
2. Apply the consistent.debugger middleware to the routes/group you need

JSON responses will include:

Do not enable the debugger in production unless you intend to expose SQL, bindings, and request input.

Route macro development

Routes available only in the local environment:

In production / staging the callback is not executed.

PostgreSQL ENUM

Macros are active during migrations (artisan migrate*) and tests (pest / phpunit).

DB macros

Blueprint macros

Failures throw Adonyarik\ConsistentApi\Exceptions\PostgresEnumException (e.g. typeAlreadyExists, typeMissing, columnHasInvalidValues, valueNotAllowed, typeStillReferenced, typeSharedAcrossTables).

Extra traits

EnumHelpers

For PHP backed enums:

Credibility

Assert that a related model "belongs" to the current one (matching IDs):

Package structure

Quick start checklist

1. composer require adonyarik/consistent-api
2. php artisan vendor:publish --tag=consistent-api-config
3. php artisan consistent:crud Post (or consistent:rebuild for an existing app)
4. Fill in #[Fillable(...)] / #[Hidden(...)] / #[Filterable(...)] / #[Sortable(...)] and request validation rules (Eloquent attributes require Laravel 13+)
5. For foreign-key/relation columns, use RelationFilter / RelationSort instead of plain column names
6. Enable any extra nested operators you need in config/filters.php
7. Optionally add middleware aliases to your api group
8. For debugging: DEBUGGER_ENABLED=true + consistent.debugger

License

MIT © Yaroslav Tyrchenko