README

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

Requirements

PHP ^8.0
Laravel (Illuminate components) ^12.0

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

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.

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

Details