Skip to main content
This guide helps you upgrade Rest Generic Class to newer versions and migrate from older implementations.

​
Current Version

Rest Generic Class is currently at version 2.1.8.

​
Requirements

​
System Requirements

  • PHP: ^8.0 or higher
  • Laravel: ^12.0 or higher
Before upgrading, ensure your application meets these minimum requirements: 
php -v  # Should show PHP 8.0 or higher
php artisan --version  # Should show Laravel 12.x

​
Upgrading the Package

​
Step 1: Update Composer

Update the package version in your composer.json: 
composer update ronu/rest-generic-class
Or require a specific version: 
composer require ronu/rest-generic-class:^2.1

​
Step 2: Publish Updated Configuration

If the configuration structure has changed, republish the config file: 
php artisan vendor:publish --tag=rest-generic-class-config --force
Using --force will overwrite your existing configuration file. Back up your current config/rest-generic-class.php before running this command if you have custom settings.

​
Step 3: Clear Caches

Clear all relevant caches: 
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
If using Spatie permissions: 
php artisan permission:cache-reset

​
Step 4: Test Your Application

Run your test suite to ensure compatibility: 
php artisan test
Manually test critical API endpoints, especially:
  • Filtering with oper parameters
  • Relation loading
  • Hierarchy queries (if used)
  • Export functionality (if used)
  • Permission checks (if using Spatie)

​
Migration Strategies

​
From Custom Implementation

If you’re migrating from a custom REST API implementation to Rest Generic Class:

​
1. Model Migration

Update your models to extend BaseModel: 
// Before
use Illuminate\Database\Eloquent\Model;

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

// After
use Ronu\RestGenericClass\Core\Models\BaseModel;

class Product extends BaseModel
{
    protected $fillable = ['name', 'price', 'stock'];
    
    const MODEL = 'product';
    const RELATIONS = ['category', 'reviews'];
}

​
2. Service Layer

Create service classes extending BaseService: 
use Ronu\RestGenericClass\Core\Services\BaseService;

class ProductService extends BaseService
{
    public function __construct()
    {
        parent::__construct(Product::class);
    }
    
    // Migrate custom methods
    public function getActiveProducts()
    {
        return $this->model->where('status', 'active')->get();
    }
}

​
3. Controller Migration

Refactor controllers to extend RestController: 
// Before
class ProductController extends Controller
{
    public function index(Request $request)
    {
        $products = Product::with('category')->paginate(15);
        return response()->json($products);
    }
}

// After
use Ronu\RestGenericClass\Core\Controllers\RestController;

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

    public function __construct(ProductService $service)
    {
        $this->service = $service;
    }
    
    // index(), show(), store(), update(), destroy() 
    // are now inherited and handle filtering automatically
}

​
4. API Compatibility

Update API clients to use the new query format: 
# Before (custom implementation)
GET /api/products?status=active&category_id=5

# After (Rest Generic Class)
POST /api/products
Content-Type: application/json

{
  "oper": {
    "and": [
      "status|=|active",
      "category_id|=|5"
    ]
  },
  "relations": ["category"]
}
Or using GET with JSON-encoded parameters: 
GET /api/products?oper={"and":["status|=|active"]}&relations=["category"]

​
From MongoDB to SQL (or vice versa)

​
MongoDB to SQL

// Before (MongoDB)
use Ronu\RestGenericClass\Core\Models\BaseModelMongo;

class Product extends BaseModelMongo
{
    protected $connection = 'mongodb';
}

// After (SQL)
use Ronu\RestGenericClass\Core\Models\BaseModel;

class Product extends BaseModel
{
    protected $connection = 'mysql';  // or 'pgsql', etc.
}

​
SQL to MongoDB

// Before (SQL)
use Ronu\RestGenericClass\Core\Models\BaseModel;

class Product extends BaseModel
{
    // ...
}

// After (MongoDB)
use Ronu\RestGenericClass\Core\Models\BaseModelMongo;

class Product extends BaseModelMongo
{
    protected $connection = 'mongodb';
}
Ensure you have mongodb/laravel installed when using BaseModelMongo:
composer require mongodb/laravel

​
Configuration Migration

​
Environment Variables

If upgrading from an older version, ensure your .env file includes new variables: 
# Logging
LOG_LEVEL=debug
LOG_QUERY=false

# Column Validation
REST_VALIDATE_COLUMNS=true
REST_STRICT_COLUMNS=true

# Cache
REST_CACHE_ENABLED=false
REST_CACHE_STORE=redis
REST_CACHE_TTL=60
REST_CACHE_TTL_LIST=60
REST_CACHE_TTL_ONE=120

# Validation Cache
REST_VALIDATION_CACHE_ENABLED=true
REST_VALIDATION_CACHE_TTL=3600
REST_VALIDATION_CACHE_PREFIX=validation
REST_VALIDATION_CONNECTION=db

​
Config File Updates

Compare your existing config/rest-generic-class.php with the published version: 
# Backup current config
cp config/rest-generic-class.php config/rest-generic-class.php.backup

# View differences
php artisan vendor:publish --tag=rest-generic-class-config --force
diff config/rest-generic-class.php.backup config/rest-generic-class.php
Manually merge any custom settings from your backup.

​
Optional Dependencies

Rest Generic Class suggests several optional packages. Install based on your needs:

​
Excel Export

composer require maatwebsite/excel
Required for: exportExcel() method

​
PDF Export

composer require barryvdh/laravel-dompdf
Required for: exportPdf() method

​
Permissions

composer require spatie/laravel-permission
Required for: Permission models, traits, and middleware

​
Module Support

composer require nwidart/laravel-modules
Required for: Module-aware permissions

​
Compatibility Notes

​
Laravel 12.x

Rest Generic Class 2.1.8 requires Laravel 12.0 or higher. If you’re on an older Laravel version:
  1. Upgrade Laravel first: https://laravel.com/docs/12.x/upgrade
  2. Then upgrade Rest Generic Class

​
PHP 8.0+

The package requires PHP 8.0 or higher. Ensure your server meets this requirement: 
php -v
If you’re on PHP 7.x, upgrade PHP before updating the package.

​
Breaking Changes

While the package maintains backward compatibility where possible, be aware of:
  1. Configuration structure changes - Always review config after updates
  2. New required constants - Some model constants may become required
  3. Deprecated methods - Check for deprecation notices in logs

​
Rollback Procedure

If you encounter issues after upgrading:

​
1. Restore Previous Version

composer require ronu/rest-generic-class:2.1.7  # Replace with your previous version

​
2. Restore Configuration

cp config/rest-generic-class.php.backup config/rest-generic-class.php

​
3. Clear Caches

php artisan config:clear
php artisan cache:clear

​
4. Report Issue

Open an issue on GitHub with:
  • Your Laravel version
  • Previous package version
  • New package version
  • Error messages
  • Steps to reproduce

​
Testing After Migration

Create a comprehensive test checklist:
  • Basic CRUD operations work
  • Filtering with oper functions correctly
  • Relations load properly
  • Pagination works
  • Hierarchy queries work (if used)
  • Export functions work (if used)
  • Permission checks pass (if using Spatie)
  • Caching behaves as expected (if enabled)
  • Multi-tenant isolation works (if applicable)
  • Custom service methods still function
  • Custom controller methods still function

​
Getting Help

If you encounter migration issues:
  1. Check the Troubleshooting guide
  2. Review the FAQ
  3. Consult the API Reference
  4. Open an issue on GitHub
  5. Include:
    • Laravel version
    • Package version (before and after)
    • PHP version
    • Error messages with full stack traces
    • Steps to reproduce the issue

​
Best Practices

​
Version Pinning

In production, pin to specific versions: 
{
  "require": {
    "ronu/rest-generic-class": "2.1.8"
  }
}
Avoid using ^ or * in production to prevent unexpected updates.

​
Staging Environment

Always test upgrades in a staging environment before production:
  1. Deploy to staging
  2. Run full test suite
  3. Manually test critical endpoints
  4. Monitor for errors
  5. Only then deploy to production

​
Incremental Updates

If you’re several versions behind, update incrementally: 
# Don't jump from 2.0.x to 2.1.8 directly
# Update step by step
composer require ronu/rest-generic-class:2.1.0
# Test
composer require ronu/rest-generic-class:2.1.5
# Test
composer require ronu/rest-generic-class:2.1.8
# Test
This makes it easier to identify which version introduced an issue.

​
Next Steps

After successful migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us