README

A Laravel package that provides base classes for RESTful CRUD with dynamic filtering, relation loading, and hierarchical listing.

Requirements

Laravel	PHP	Test runtime
12.61.1+	8.2+	PHPUnit 11
13.12+	8.3+	PHPUnit 12

The package keeps Laravel 12 support while adding Laravel 13 support. See the Laravel 13 migration plan and audit. There is also a detailed Spanish Laravel 13 migration guide for junior developers.

Installation

composer require ronu/rest-generic-class

Publish configuration (optional)

php artisan vendor:publish --tag=rest-generic-class-config

Quickstart

1) Model

<?php

namespace App\Models;

use Ronu\RestGenericClass\Core\Models\BaseModel;

class Product extends BaseModel
{
    protected $fillable = ['name', 'price', 'stock', 'category_id'];

    const MODEL = 'product';
    const RELATIONS = ['category', 'reviews'];

    public function category()
    {
        return $this->belongsTo(Category::class);
    }

    public function reviews()
    {
        return $this->hasMany(Review::class);
    }
}

2) Service

<?php

namespace App\Services;

use App\Models\Product;
use Ronu\RestGenericClass\Core\Services\BaseService;

class ProductService extends BaseService
{
    public function __construct()
    {
        parent::__construct(Product::class);
    }
}

3) Controller

<?php

namespace App\Http\Controllers\Api;

use App\Models\Product;
use App\Services\ProductService;
use Ronu\RestGenericClass\Core\Controllers\RestController;

class ProductController extends RestController
{
    protected $modelClass = Product::class;

    public function __construct(ProductService $service)
    {
        $this->service = $service;
    }
}

4) Routes

use App\Http\Controllers\Api\ProductController;

Route::prefix('v1')->group(function () {
    Route::apiResource('products', ProductController::class);
    Route::post('products/update-multiple', [ProductController::class, 'updateMultiple']);
});

5) Query with filtering and relations

GET /api/v1/products?select=["id","name"]&relations=["category:id,name"]

{
  "oper": {
    "and": ["status|=|active", "price|>=|50"]
  }
}

Configuration

Publish the config file and adjust values in config/rest-generic-class.php.

Environment variables:

LOG_LEVEL (default: debug)
LOG_QUERY (default: false)
REST_VALIDATE_COLUMNS (default: true)
REST_STRICT_COLUMNS (default: true)
REST_CACHE_ENABLED (default: false)
REST_CACHE_STORE (default: CACHE_STORE; supports redis, database, file, memcached, etc.)
REST_CACHE_TTL (default: 60 seconds)
REST_CACHE_TTL_LIST / REST_CACHE_TTL_ONE
REST_VALIDATION_CACHE_ENABLED (default: true)
REST_VALIDATION_CACHE_TTL (default: 3600 seconds)
REST_VALIDATION_CACHE_PREFIX (default: validation)
REST_VALIDATION_CONNECTION (default: db)

Cache strategy (Laravel native / Redis / database)

This package now supports generic cache integration via Laravel Cache stores.

How it works

Cache is applied in BaseService for read operations: list_all and get_one.
Cache key fingerprint includes: model, operation, route, query params, auth user, selected headers, normalized params, and a model cache version.
Any successful write (create, update, destroy, destroybyid) bumps a model-level cache version to avoid stale reads without needing tags.
Laravel 13's secure cache.serializable_classes=false default is honored: array payloads are cached, while paginator objects are not cached unless the host application supplies an explicit class allowlist.
Cache keys use the rgc:v2 namespace so incompatible Laravel 12 cache entries are not reused after an upgrade.

Store selection

Use any Laravel cache store by setting:

REST_CACHE_ENABLED=true
REST_CACHE_STORE=redis
# or: database, file, memcached, dynamodb, etc.

Request-aware behavior

You can control cache per request:

cache=false disables cache for that request.
cache_ttl=120 overrides TTL (seconds) for that request.

Example:

GET /api/v1/products?cache_ttl=120&select=["id","name"]

Multi-tenant / locale aware keys

By default cache varies by Accept-Language and X-Tenant-Id headers to avoid cross-tenant or cross-locale data leaks.

Common scenarios

1) Bulk update

POST /api/v1/products/update-multiple
Content-Type: application/json

{
  "product": [
    {"id": 10, "stock": 50},
    {"id": 11, "stock": 0}
  ]
}

2) Hierarchy listing

{
  "hierarchy": {
    "filter_mode": "with_descendants",
    "children_key": "children",
    "max_depth": 3
  }
}

3) Permission sync (Spatie)

POST /api/permissions/assign_roles
Content-Type: application/json

{
  "roles": ["admin"],
  "guard": "api",
  "mode": "SYNC",
  "perms": ["products.view", "products.create"]
}

Edge scenarios

Config caching hides env updates until you clear the config cache.
Deep hierarchy trees can time out without max_depth.
Excessive filter conditions trigger safety limits.

See Edge and extreme scenarios for detailed guidance.

API reference

Troubleshooting

Start with Troubleshooting for common errors such as invalid relations, operator errors, and missing optional packages.

Documentation

Contributing / Security

Please open issues and pull requests on GitHub. For security concerns, report them privately to the maintainer email listed in the package metadata.

ronu / rest-generic-class

Maintainers

Package info

Statistics

Security