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
• 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.

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

• Public API
• Middleware
• Exceptions

Troubleshooting

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

Documentation

• Documentation index (EN)
• Documentation index (ES)
• Quickstart
• Configuration reference
• Scenarios

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.