Migration Guide

Upgrading and migrating Rest Generic Class versions

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:

• Review the Configuration overview for all options
• Check out Advanced filtering for powerful query features
• Optimize your implementation with the Caching guide
• Ensure security with the Security guide